本页按字母顺序记录了 CadQuery 类的所有方法和函数。

Core Classes

Topological Classes

Geometry Classes

Selector Classes

Class Details

Bases: object
工作平面和形状对象的嵌套组件，定义了它们的相对位置。

Parameters

• obj (Optional[Union[Shape, Workplane]]) –

• loc (Location) –

• name (str) –

• color (Optional[Color]) –

• metadata (Dict[str, Any])

• loc (Optional[Location]) – location of the root object (default: None, interpreted as identity transformation)

• name (Optional[str]) – unique name of the root object (default: None, resulting in an UUID being generated)

• color (Optional[Color]) – color of the added object (default: None)

• metadata (Optional[Dict[str, Any]]) – a store for user-defined metadata (default: None)

ReturnsAn Assembly object.
To create an empty assembly use:

assy = Assembly(None)

To create one constraint a root object:

b = Workplane().box(1, 1, 1)
assy = Assembly(b, Location(Vector(0, 0, 1)), name="root")

Assembly iterator yielding shapes, names, locations and colors.
Parameters- loc (Optional[Location]) –

• name (Optional[str]) –

• color (Optional[Color]) –

Return typeIterator[Tuple[Shape, str, Location, Optional[Color]]]

list of weak references to the object (if defined)

• exportType (Optional[Literal['STEP', 'XML', 'GLTF', 'VTKJS', 'VRML', 'STL']]) – export format (default: None, results in format being inferred form the path)

• mode (Literal['default', 'fused']) – STEP only - See exportAssembly().

• tolerance (float) – the deflection tolerance, in model units. Only used for glTF, VRML. Default 0.1.

• angularTolerance (float) – the angular tolerance, in radians. Only used for glTF, VRML. Default 0.1.

• **kwargs – Additional keyword arguments. Only used for STEP, glTF and STL. See exportAssembly().

• ascii (bool) – STL only - Sets whether or not STL export should be text or binary

Return typeAssembly

2. a vector, containing the x,y,z values to add

3. another bounding box, where a new box will be created that encloses both.

This bounding box is not changed.
Parameters- obj (Union[Tuple[float, float, float], Vector, BoundBox]) –

• tol (Optional[float]) –

Return typeBoundBox
enlarge(tol: float)→ BoundBox[source]Returns a modified (expanded) bounding box, expanded in all directions by the tolerance value.
This means that the minimum values of its X, Y and Z intervals of the bounding box are reduced by the absolute value of tol, while the maximum values are increased by the same amount.
Parameterstol (float) –
Return typeBoundBox
staticfindOutsideBox2D(bb1: BoundBox, bb2: BoundBox)→ Optional[BoundBox][source]Compares bounding boxes
Compares bounding boxes. Returns none if neither is inside the other. Returns the outer one if either is outside the other.
BoundBox.isInside works in 3d, but this is a 2d bounding box, so it doesn’t work correctly plus, there was all kinds of rounding error in the built-in implementation i do not understand.
Parameters- bb1 (BoundBox) –

• bb2 (BoundBox) –

Return typeOptional[BoundBox]
isInside(b2: BoundBox)→ bool[source]Is the provided bounding box inside this one?
Parametersb2 (BoundBox) –
Return typebool
cadquery.CQalias of Workplane
classcadquery.Color(name: str)[source]classcadquery.Color(r: float, g: float, b: float, a: float = 0)classcadquery.ColorBases: object
Wrapper for the OCCT color object Quantity_ColorRGBA.
init(name: str)[source]init(r: float, g: float, b: float, a: float = 0)init()weakreflist of weak references to the object (if defined)
toTuple()→ Tuple[float, float, float, float][[source]](cadquery.readthedocs...)Convert Color to RGB tuple.
Return typeTuple[float, float, float, float]
classcadquery.Compound(obj: TopoDS_Shape)[source]Bases: Shape, Mixin3D
a collection of disconnected solids
Parametersobj (TopoDS_Shape) –
bool()→ bool[source]Check if empty.
Return typebool
ancestors(shape: Shape, kind: Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound'])→ Compound[source]Iterate over ancestors, i.e. shapes of same kind within shape that contain elements of self.
Parameters- shape (Shape) –

• kind (Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound']) –

Return typeCompound
cut(toCut: Shape, tol: Optional[float] = None)→ Compound[source]Remove the positional arguments from this Shape.
Parameters- *tol** (Optional[float]) – Fuzzy mode tolerance

• toCut (Shape) –

Return typeCompound
fuse(toFuse: Shape, glue: bool = False, tol: Optional[float] = None)→ Compound[source]Fuse shapes together
Parameters- *toFuse** (Shape) –

• glue (bool) –

• tol (Optional[float]) –

Return typeCompound
intersect(toIntersect: Shape, tol: Optional[float] = None)→ Compound[source]Intersection of the positional arguments and this Shape.
Parameters- *tol** (Optional[float]) – Fuzzy mode tolerance

• toIntersect (Shape) –

Return typeCompound
classmethodmakeCompound(listOfShapes: Iterable[Shape])→ Compound[source]Create a compound out of a list of shapes
ParameterslistOfShapes (Iterable[Shape]) –
Return typeCompound
classmethodmakeText(text: str, size: float, height: float, font: str = 'Arial', fontPath: Optional[str] = None, kind: Literal['regular', 'bold', 'italic'] = 'regular', halign: Literal['center', 'left', 'right'] = 'center', valign: Literal['center', 'top', 'bottom'] = 'center', position: Plane = Plane(origin=(0.0, 0.0, 0.0), xDir=(1.0, 0.0, 0.0), normal=(0.0, 0.0, 1.0)))→ Shape[source]Create a 3D text
Parameters- text (str) –

• size (float) –

• height (float) –

• font (str) –

• fontPath (Optional[str]) –

• kind (Literal['regular', 'bold', 'italic']) –

• halign (Literal['center', 'left', 'right']) –

• valign (Literal['center', 'top', 'bottom']) –

• position (Plane) –

Return typeShape
remove(shape: Shape)[source]Remove the specified shape.
Parametersshape (Shape) –
siblings(shape: Shape, kind: Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound'], level: int = 1)→ Compound[source]Iterate over siblings, i.e. shapes within shape that share subshapes of kind with the elements of self.
Parameters- shape (Shape) –

• kind (Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound']) –

• level (int) –

Return typeCompound
cadquery.Constraintalias of ConstraintSpec
classcadquery.DirectionMinMaxSelector(vector: Vector, directionMax: bool = True, tolerance: float = 0.0001)[source]Bases: CenterNthSelector
Selects objects closest or farthest in the specified direction.
Applicability:All object types. for a vertex, its point is used. for all other kinds of objects, the center of mass of the object is used.
You can use the string shortcuts >(X|Y|Z) or <(X|Y|Z) if you want to select based on a cardinal direction.
For example this:

CQ(aCube).faces(DirectionMinMaxSelector((0, 0, 1), True))

Means to select the face having the center of mass farthest in the positive z direction, and is the same as:

CQ(aCube).faces(">Z")

Parameters- vector (Vector) –

• directionMax (bool) –

• tolerance (float) –

init(vector: Vector, directionMax: bool = True, tolerance: float = 0.0001)[source]Parameters- vector (Vector) –

• directionMax (bool) –

• tolerance (float) –

classcadquery.DirectionSelector(vector: Vector, tolerance: float = 0.0001)[source]Bases: BaseDirSelector
Selects objects aligned with the provided direction.
Applicability:Linear Edges Planar Faces
Use the string syntax shortcut +/-(X|Y|Z) if you want to select based on a cardinal direction.
Example:

CQ(aCube).faces(DirectionSelector((0, 0, 1)))

selects faces with the normal in the z direction, and is equivalent to:

CQ(aCube).faces("+Z")

Parameters- vector (Vector) –

• tolerance (float) –

test(vec: Vector)→ bool[source]Test a specified vector. Subclasses override to provide other implementations
Parametersvec (Vector) –
Return typebool
classcadquery.Edge(obj: TopoDS_Shape)[source]Bases: Shape, Mixin1D
A trimmed curve that represents the border of a face
Parametersobj (TopoDS_Shape) –
arcCenter()→ Vector[source]Center of an underlying circle or ellipse geometry.
Return typeVector
close()→ Union[Edge, Wire][source]Close an Edge
Return typeUnion[Edge, Wire]
classmethodmakeEllipse(x_radius: float, y_radius: float, pnt: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 0.0), dir: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 1.0), xdir: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (1.0, 0.0, 0.0), angle1: float = 360.0, angle2: float = 360.0, sense: ~typing.Literal[-1, 1] = 1)→ Edge[source]Makes an Ellipse centered at the provided point, having normal in the provided direction.
Parameters- cls –

• x_radius (float) – x radius of the ellipse (along the x-axis of plane the ellipse should lie in)

• y_radius (float) – y radius of the ellipse (along the y-axis of plane the ellipse should lie in)

• pnt (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – vector representing the center of the ellipse

• dir (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – vector representing the direction of the plane the ellipse should lie in

• angle1 (float) – start angle of arc

• angle2 (float) – end angle of arc (angle2 == angle1 return closed ellipse = default)

• sense (Literal[-1, 1]) – clockwise (-1) or counter clockwise (1)

• xdir (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

Returnsan Edge
Return typeEdge
classmethodmakeLine(v1: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], v2: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])→ Edge[source]Create a line between two points
Parameters- v1 (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – Vector that represents the first point

• v2 (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – Vector that represents the second point

ReturnsA linear edge between the two provided points
Return typeEdge
classmethodmakeSpline(listOfVector: List[Vector], tangents: Optional[Sequence[Vector]] = None, periodic: bool = False, parameters: Optional[Sequence[float]] = None, scale: bool = True, tol: float = 1e-06)→ Edge[source]Interpolate a spline through the provided points.
Parameters- listOfVector (List[Vector]) – a list of Vectors that represent the points

• tangents (Optional[Sequence[Vector]]) – tuple of Vectors specifying start and finish tangent

• periodic (bool) – creation of periodic curves

• parameters (Optional[Sequence[float]]) – the value of the parameter at each interpolation point. (The interpolated curve is represented as a vector-valued function of a scalar parameter.) If periodic == True, then len(parameters) must be len(intepolation points) + 1, otherwise len(parameters) must be equal to len(interpolation points).

• scale (bool) – whether to scale the specified tangent vectors before interpolating. Each tangent is scaled, so it’s length is equal to the derivative of the Lagrange interpolated curve. I.e., set this to True, if you want to use only the direction of the tangent vectors specified by tangents, but not their magnitude.

• tol (float) – tolerance of the algorithm (consult OCC documentation). Used to check that the specified points are not too close to each other, and that tangent vectors are not too short. (In either case interpolation may fail.)

Returnsan Edge
Return typeEdge
classmethodmakeSplineApprox(listOfVector: List[Vector], tol: float = 0.001, smoothing: Optional[Tuple[float, float, float]] = None, minDeg: int = 1, maxDeg: int = 6)→ Edge[source]Approximate a spline through the provided points.
Parameters- listOfVector (List[Vector]) – a list of Vectors that represent the points

• tol (float) – tolerance of the algorithm (consult OCC documentation).

• smoothing (Optional[Tuple[float, float, float]]) – optional tuple of 3 weights use for variational smoothing (default: None)

• minDeg (int) – minimum spline degree. Enforced only when smothing is None (default: 1)

• maxDeg (int) – maximum spline degree (default: 6)

Returnsan Edge
Return typeEdge
classmethodmakeTangentArc(v1: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], v2: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], v3: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])→ Edge[source]Makes a tangent arc from point v1, in the direction of v2 and ends at v3.
Parameters- cls –

• v1 (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – start vector

• v2 (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – tangent vector

• v3 (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – end vector

Returnsan edge
Return typeEdge
classmethodmakeThreePointArc(v1: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], v2: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], v3: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])→ Edge[source]Makes a three point arc through the provided points
Parameters- cls –

• v1 (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – start vector

• v2 (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – middle vector

• v3 (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – end vector

Returnsan edge object through the three points
Return typeEdge
classcadquery.Face(obj: TopoDS_Shape)[source]Bases: Shape
a bounded surface that represents part of the boundary of a solid
Parametersobj (TopoDS_Shape) –
Center()→ Vector[source]ReturnsThe point of the center of mass of this Shape
Return typeVector
chamfer2D(d: float, vertices: Iterable[Vertex])→ Face[source]Apply 2D chamfer to a face
Parameters- d (float) –

• vertices (Iterable[Vertex]) –

Return typeFace
fillet2D(radius: float, vertices: Iterable[Vertex])→ Face[source]Apply 2D fillet to a face
Parameters- radius (float) –

• vertices (Iterable[Vertex]) –

Return typeFace
classmethodmakeFromWires(outerWire: Wire, innerWires: List[Wire] = [])→ Face[source]Makes a planar face from one or more wires
Parameters- outerWire (Wire) –

• innerWires (List[Wire]) –

Return typeFace
classmethodmakeNSidedSurface(edges: ~typing.Iterable[~typing.Union[~cadquery.occ_impl.shapes.Edge, ~cadquery.occ_impl.shapes.Wire]], constraints: ~typing.Iterable[~typing.Union[~cadquery.occ_impl.shapes.Edge, ~cadquery.occ_impl.shapes.Wire, ~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]], ~OCP.gp.gp_Pnt]], continuity: ~OCP.GeomAbs.GeomAbs_Shape = <GeomAbs_Shape.GeomAbs_C0: 0>, degree: int = 3, nbPtsOnCur: int = 15, nbIter: int = 2, anisotropy: bool = False, tol2d: float = 1e-05, tol3d: float = 0.0001, tolAng: float = 0.01, tolCurv: float = 0.1, maxDeg: int = 8, maxSegments: int = 9)→ Face[source]Returns a surface enclosed by a closed polygon defined by ‘edges’ and ‘constraints’.
Parameters- edges (list of edges or wires) – edges

• constraints (list of points or edges) – constraints

• continuity (GeomAbs_Shape) – OCC.Core.GeomAbs continuity condition

• degree (int) – >=2

• nbPtsOnCur (int) – number of points on curve >= 15

• nbIter (int) – number of iterations >= 2

• anisotropy (bool) – bool Anisotropy

• tol2d (float) – 2D tolerance >0

• tol3d (float) – 3D tolerance >0

• tolAng (float) – angular tolerance

• tolCurv (float) – tolerance for curvature >0

• maxDeg (int) – highest polynomial degree >= 2

• maxSegments (int) – greatest number of segments >= 2

Return typeFace
classmethodmakeRuledSurface(edgeOrWire1: Edge, edgeOrWire2: Edge)→ Face[source]classmethodmakeRuledSurface(edgeOrWire1: Wire, edgeOrWire2: Wire)→ FacemakeRuledSurface(Edge|Wire,Edge|Wire) – Make a ruled surface Create a ruled surface out of two edges or wires. If wires are used then these must have the same number of edges
classmethodmakeSplineApprox(points: List[List[Vector]], tol: float = 0.01, smoothing: Optional[Tuple[float, float, float]] = None, minDeg: int = 1, maxDeg: int = 3)→ Face[source]Approximate a spline surface through the provided points.
Parameters- points (List[List[Vector]]) – a 2D list of Vectors that represent the points

• tol (float) – tolerance of the algorithm (consult OCC documentation).

• smoothing (Optional[Tuple[float, float, float]]) – optional tuple of 3 weights use for variational smoothing (default: None)

• minDeg (int) – minimum spline degree. Enforced only when smothing is None (default: 1)

• maxDeg (int) – maximum spline degree (default: 6)

Return typeFace
normalAt(locationVector: Optional[Vector] = None)→ Vector[source]Computes the normal vector at the desired location on the face.
Returnsa vector representing the direction
ParameterslocationVector (a vector that lies on the surface.) – the location to compute the normal at. If none, the center of the face is used.
Return typeVector
thicken(thickness: float)→ Solid[source]Return a thickened face
Parametersthickness (float) –
Return typeSolid
toArcs(tolerance: float = 0.001)→ Face[source]Approximate planar face with arcs and straight line segments.
Parameterstolerance (float) – Approximation tolerance.
Return typeFace
toPln()→ gp_Pln[source]Convert this face to a gp_Pln.
Note the Location of the resulting plane may not equal the center of this face, however the resulting plane will still contain the center of this face.
Return typegp_Pln
classcadquery.Location[source]classcadquery.Location(t: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])classcadquery.Location(t: Plane)classcadquery.Location(t: Plane, v: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])classcadquery.Location(t: TopLoc_Location)classcadquery.Location(t: gp_Trsf)classcadquery.Location(t: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], ax: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], angle: float)Bases: object
Location in 3D space. Depending on usage can be absolute or relative.
This class wraps the TopLoc_Location class from OCCT. It can be used to move Shape objects in both relative and absolute manner. It is the preferred type to locate objects in CQ.
init()→ None[source]init(t: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])→ None__init__(t: Plane)→ None__init__(t: Plane, v: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])→ None__init__(t: TopLoc_Location)→ None__init__(t: gp_Trsf)→ None__init__(t: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], ax: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], angle: float)→ None__weakref__list of weak references to the object (if defined)
toTuple()→ Tuple[Tuple[float, float, float], Tuple[float, float, float]][[source]](cadquery.readthedocs...)Convert the location to a translation, rotation tuple.
Return typeTuple[Tuple[float, float, float], Tuple[float, float, float]]
classcadquery.Matrix[source]classcadquery.Matrix(matrix: Union[gp_GTrsf, gp_Trsf])classcadquery.Matrix(matrix: Sequence[Sequence[float]])Bases: object
A 3d , 4x4 transformation matrix.
Used to move geometry in space.
The provided “matrix” parameter may be None, a gp_GTrsf, or a nested list of values.
If given a nested list, it is expected to be of the form:

[[m11, m12, m13, m14],[m21, m22, m23, m24], [m31, m32, m33, m34]]

A fourth row may be given, but it is expected to be: [0.0, 0.0, 0.0, 1.0] since this is a transform matrix.
getitem(rc: Tuple[int, int])→ float[source]Provide Matrix[r, c] syntax for accessing individual values. The row and column parameters start at zero, which is consistent with most python libraries, but is counter to gp_GTrsf(), which is 1-indexed.
Parametersrc (Tuple[int, int]) –
Return typefloat
init()→ None[source]init(matrix: Union[gp_GTrsf, gp_Trsf])→ None__init__(matrix: Sequence[Sequence[float]])→ None__repr__()→ str[source]Generate a valid python expression representing this Matrix
Return typestr
weakreflist of weak references to the object (if defined)
transposed_list()→ Sequence[float][[source]](cadquery.readthedocs...)Needed by the cqparts gltf exporter
Return typeSequence[float]
classcadquery.NearestToPointSelector(pnt)[source]Bases: Selector
Selects object nearest the provided point.
If the object is a vertex or point, the distance is used. For other kinds of shapes, the center of mass is used to to compute which is closest.
Applicability: All Types of Shapes
Example:

CQ(aCube).vertices(NearestToPointSelector((0, 1, 0)))

returns the vertex of the unit cube closest to the point x=0,y=1,z=0
init(pnt)[source]filter(objectList: Sequence[Shape])[source]Filter the provided list.
The default implementation returns the original list unfiltered.
ParametersobjectList (list of OCCT primitives) – list to filter
Returnsfiltered list
classcadquery.ParallelDirSelector(vector: Vector, tolerance: float = 0.0001)[source]Bases: BaseDirSelector
Selects objects parallel with the provided direction.
Applicability:Linear Edges Planar Faces
Use the string syntax shortcut |(X|Y|Z) if you want to select based on a cardinal direction.
Example:

CQ(aCube).faces(ParallelDirSelector((0, 0, 1)))

selects faces with the normal parallel to the z direction, and is equivalent to:

CQ(aCube).faces("|Z")

Parameters- vector (Vector) –

• tolerance (float) –

test(vec: Vector)→ bool[source]Test a specified vector. Subclasses override to provide other implementations
Parametersvec (Vector) –
Return typebool
classcadquery.PerpendicularDirSelector(vector: Vector, tolerance: float = 0.0001)[source]Bases: BaseDirSelector
Selects objects perpendicular with the provided direction.
Applicability:Linear Edges Planar Faces
Use the string syntax shortcut #(X|Y|Z) if you want to select based on a cardinal direction.
Example:

CQ(aCube).faces(PerpendicularDirSelector((0, 0, 1)))

selects faces with the normal perpendicular to the z direction, and is equivalent to:

CQ(aCube).faces("#Z")

Parameters- vector (Vector) –

• tolerance (float) –

test(vec: Vector)→ bool[source]Test a specified vector. Subclasses override to provide other implementations
Parametersvec (Vector) –
Return typebool
classcadquery.Plane(origin: Union[Tuple[float, float, float], Vector], xDir: Optional[Union[Tuple[float, float, float], Vector]] = None, normal: Union[Tuple[float, float, float], Vector] = (0, 0, 1))[source]Bases: object
A 2D coordinate system in space
A 2D coordinate system in space, with the x-y axes on the plane, and a particular point as the origin.
A plane allows the use of 2D coordinates, which are later converted to global, 3d coordinates when the operations are complete.
Frequently, it is not necessary to create work planes, as they can be created automatically from faces.
Parameters- origin (Union[Tuple[float, float, float], Vector]) –

• xDir (Vector) –

• normal (Union[Tuple[float, float, float], Vector]) –

eq(other)[source]Return self==value.
hash= Noneinit(origin: Union[Tuple[float, float, float], Vector], xDir: Optional[Union[Tuple[float, float, float], Vector]] = None, normal: Union[Tuple[float, float, float], Vector] = (0, 0, 1))[source]Create a Plane with an arbitrary orientation
Parameters- origin (Union[Tuple[float, float, float], Vector]) – the origin in global coordinates

• xDir (Optional[Union[Tuple[float, float, float], Vector]]) – an optional vector representing the xDirection.

• normal (Union[Tuple[float, float, float], Vector]) – the normal direction for the plane

RaisesValueError – if the specified xDir is not orthogonal to the provided normal
ne(other)[source]Return self!=value.
repr()[source]Return repr(self).
weakreflist of weak references to the object (if defined)
classmethodnamed(stdName: str, origin=(0, 0, 0))→ Plane[source]Create a predefined Plane based on the conventional names.
Parameters- stdName (string) – one of (XY|YZ|ZX|XZ|YX|ZY|front|back|left|right|top|bottom)

• origin (3-tuple of the origin of the new plane, in global coordinates.) – the desired origin, specified in global coordinates

Return typePlane
Available named planes are as follows. Direction references refer to the global directions.

rotated(rotate=(0, 0, 0))[source]Returns a copy of this plane, rotated about the specified axes
Since the z axis is always normal the plane, rotating around Z will always produce a plane that is parallel to this one.
The origin of the workplane is unaffected by the rotation.
Rotations are done in order x, y, z. If you need a different order, manually chain together multiple rotate() commands.
Parametersrotate – Vector [xDegrees, yDegrees, zDegrees]
Returnsa copy of this plane rotated as requested.
setOrigin2d(x, y)[source]Set a new origin in the plane itself
Set a new origin in the plane itself. The plane’s orientation and xDrection are unaffected.
Parameters- x (float) – offset in the x direction

• y (float) – offset in the y direction

Returnsvoid
The new coordinates are specified in terms of the current 2D system. As an example:
p = Plane.XY() p.setOrigin2d(2, 2) p.setOrigin2d(2, 2)
results in a plane with its origin at (x, y) = (4, 4) in global coordinates. Both operations were relative to local coordinates of the plane.
toLocalCoords(obj)[source]Project the provided coordinates onto this plane
Parametersobj – an object or vector to convert
Returnsan object of the same type, but converted to local coordinates
Most of the time, the z-coordinate returned will be zero, because most operations based on a plane are all 2D. Occasionally, though, 3D points outside of the current plane are transformed. One such example is Workplane.box(), where 3D corners of a box are transformed to orient the box in space correctly.
toWorldCoords(tuplePoint)→ Vector[source]Convert a point in local coordinates to global coordinates
ParameterstuplePoint (a 2 or three tuple of float. The third value is taken to be zero if not supplied.) – point in local coordinates to convert.
Returnsa Vector in global coordinates
Return typeVector
classcadquery.Selector[source]Bases: object
Filters a list of objects.
Filters must provide a single method that filters objects.
weakreflist of weak references to the object (if defined)
filter(objectList: Sequence[Shape])→ List[Shape][[source]](cadquery.readthedocs...)Filter the provided list.
The default implementation returns the original list unfiltered.
ParametersobjectList (list of OCCT primitives) – list to filter
Returnsfiltered list
Return typeList[Shape]
classcadquery.Shape(obj: TopoDS_Shape)[source]Bases: object
Represents a shape in the system. Wraps TopoDS_Shape.
Parametersobj (TopoDS_Shape) –
Area()→ float[source]ReturnsThe surface area of all faces in this Shape
Return typefloat
BoundingBox(tolerance: Optional[float] = None)→ BoundBox[source]Create a bounding box for this Shape.
Parameterstolerance (Optional[float]) – Tolerance value passed to BoundBox
ReturnsA BoundBox object for this Shape
Return typeBoundBox
Center()→ Vector[source]ReturnsThe point of the center of mass of this Shape
Return typeVector
CenterOfBoundBox(tolerance: Optional[float] = None)→ Vector[source]Parameterstolerance (Optional[float]) – Tolerance passed to the BoundingBox() method
ReturnsCenter of the bounding box of this shape
Return typeVector
Closed()→ bool[source]ReturnsThe closedness flag
Return typebool
staticCombinedCenter(objects: Iterable[Shape])→ Vector[source]Calculates the center of mass of multiple objects.
Parametersobjects (Iterable[Shape]) – A list of objects with mass
Return typeVector
staticCombinedCenterOfBoundBox(objects: List[Shape])→ Vector[source]Calculates the center of a bounding box of multiple objects.
Parametersobjects (List[Shape]) – A list of objects
Return typeVector
CompSolids()→ List[CompSolid][[source]](cadquery.readthedocs...)ReturnsAll the compsolids in this Shape
Return typeList[CompSolid]
Compounds()→ List[Compound][source]ReturnsAll the compounds in this Shape
Return typeList[Compound]
Edges()→ List[Edge][source]ReturnsAll the edges in this Shape
Return typeList[Edge]
Faces()→ List[Face][source]ReturnsAll the faces in this Shape
Return typeList[Face]
Shells()→ List[Shell][source]ReturnsAll the shells in this Shape
Return typeList[Shell]
Solids()→ List[Solid][source]ReturnsAll the solids in this Shape
Return typeList[Solid]
Vertices()→ List[Vertex][source]ReturnsAll the vertices in this Shape
Return typeList[Vertex]
Volume()→ float[source]ReturnsThe volume of this Shape
Return typefloat
Wires()→ List[Wire][source]ReturnsAll the wires in this Shape
Return typeList[Wire]
eq(other)→ bool[source]Return self==value.
Return typebool
hash()→ int[source]Return hash(self).
Return typeint
init(obj: TopoDS_Shape)[source]Parametersobj (TopoDS_Shape) –
iter()→ Iterator[Shape][source]Iterate over subshapes.
Return typeIterator[Shape]
weakreflist of weak references to the object (if defined)
ancestors(shape: Shape, kind: Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound'])→ Compound[source]Iterate over ancestors, i.e. shapes of same kind within shape that contain self.
Parameters- shape (Shape) –

• kind (Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound']) –

Return typeCompound
classmethodcast(obj: TopoDS_Shape, forConstruction: bool = False)→ Shape[source]Returns the right type of wrapper, given a OCCT object
Parameters- obj (TopoDS_Shape) –

• forConstruction (bool) –

Return typeShape
staticcenterOfMass(obj: Shape)→ Vector[source]Calculates the center of ‘mass’ of an object.
Parametersobj (Shape) – Compute the center of mass of this object
Return typeVector
clean()→ T[source]Experimental clean using ShapeUpgrade
Parametersself (T) –
Return typeT
staticcomputeMass(obj: Shape)→ float[source]Calculates the ‘mass’ of an object.
Parametersobj (Shape) – Compute the mass of this object
Return typefloat
copy(mesh: bool = False)→ T[source]Creates a new object that is a copy of this object.
Parameters- self (T) –

• mesh (bool) – should I copy the triangulation too (default: False)

Returnsa copy of the object
Return typeT
cut(toCut: Shape, tol: Optional[float] = None)→ Shape[source]Remove the positional arguments from this Shape.
Parameters- *tol** (Optional[float]) – Fuzzy mode tolerance

• toCut (Shape) –

Return typeShape
distance(other: Shape)→ float[source]Minimal distance between two shapes
Parametersother (Shape) –
Return typefloat
distances(others: Shape)→ Iterator[float][[source]](https://cadquery.readthedocs.io/en/latest/_modules/cadquery/occ_impl/shapes.html#Shape.distances)Minimal distances to between self and other shapes
Parameters*others* (Shape) –
Return typeIterator[float]
edges(selector: Optional[Union[Selector, str]] = None)→ Shape[source]Select edges.
Parameters*selector* (Optional[Union[Selector, str]]) –
Return typeShape
exportBrep(f: Union[str, BytesIO])→ bool[source]Export this shape to a BREP file
Parameters*f* (Union[str, BytesIO]) –
Return typebool
exportStep(fileName: str, *kwargs)→ IFSelect_ReturnStatus[source]Export this shape to a STEP file.
kwargs is used to provide optional keyword arguments to configure the exporter.
Parameters- fileName (str) – Path and filename for writing.

• write_pcurves (bool) –
  Enable or disable writing parametric curves to the STEP file. Default True.
  If False, writes STEP file without pcurves. This decreases the size of the resulting STEP file.

• precision_mode (int) – Controls the uncertainty value for STEP entities. Specify -1, 0, or 1. Default 0. See OCCT documentation.

Return typeIFSelect_ReturnStatus
exportStl(fileName: str, tolerance: float = 0.001, angularTolerance: float = 0.1, ascii: bool = False, relative: bool = True, parallel: bool = True)→ bool[source]Exports a shape to a specified STL file.
Parameters- fileName (str) – The path and file name to write the STL output to.

• tolerance (float) – A linear deflection setting which limits the distance between a curve and its tessellation. Setting this value too low will result in large meshes that can consume computing resources. Setting the value too high can result in meshes with a level of detail that is too low. Default is 1e-3, which is a good starting point for a range of cases.

• angularTolerance (float) – Angular deflection setting which limits the angle between subsequent segments in a polyline. Default is 0.1.

• ascii (bool) – Export the file as ASCII (True) or binary (False) STL format. Default is binary.

• relative (bool) – If True, tolerance will be scaled by the size of the edge being meshed. Default is True. Setting this value to True may cause large features to become faceted, or small features dense.

• parallel (bool) – If True, OCCT will use parallel processing to mesh the shape. Default is True.

Return typebool
faces(selector: Optional[Union[Selector, str]] = None)→ Shape[source]Select faces.
Parametersselector (Optional[Union[Selector, str]]) –
Return typeShape
facesIntersectedByLine(point: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], axis: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], tol: float = 0.0001, direction: Optional[Literal['AlongAxis', 'Opposite']] = None)[source]Computes the intersections between the provided line and the faces of this Shape
Parameters- point (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – Base point for defining a line

• axis (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – Axis on which the line rests

• tol (float) – Intersection tolerance

• direction (Optional[Literal['AlongAxis', 'Opposite']]) – Valid values: “AlongAxis”, “Opposite”; If specified, will ignore all faces that are not in the specified direction including the face where the point lies if it is the case

ReturnsA list of intersected faces sorted by distance from point
fix()→ T[source]Try to fix shape if not valid
Parametersself (T) –
Return typeT
fuse(toFuse: Shape, glue: bool = False, tol: Optional[float] = None)→ Shape[source]Fuse the positional arguments with this Shape.
Parameters- *glue** (bool) – Sets the glue option for the algorithm, which allows increasing performance of the intersection of the input shapes

• tol (Optional[float]) – Fuzzy mode tolerance

• toFuse (Shape) –

Return typeShape
geomType()→ Literal['Vertex', 'Wire', 'Shell', 'Solid', 'Compound', 'PLANE', 'CYLINDER', 'CONE', 'SPHERE', 'TORUS', 'BEZIER', 'BSPLINE', 'REVOLUTION', 'EXTRUSION', 'OFFSET', 'OTHER', 'LINE', 'CIRCLE', 'ELLIPSE', 'HYPERBOLA', 'PARABOLA'][[source]](cadquery.readthedocs...)Gets the underlying geometry type.
Implementations can return any values desired, but the values the user uses in type filters should correspond to these.
As an example, if a user does:

CQ(object).faces("%mytype")

The expectation is that the geomType attribute will return ‘mytype’
The return values depend on the type of the shape:
Vertex: always ‘Vertex’
Edge: LINE, CIRCLE, ELLIPSE, HYPERBOLA, PARABOLA, BEZIER,
BSPLINE, OFFSET, OTHER
Face: PLANE, CYLINDER, CONE, SPHERE, TORUS, BEZIER, BSPLINE,
REVOLUTION, EXTRUSION, OFFSET, OTHER
Solid: ‘Solid’
Shell: ‘Shell’
Compound: ‘Compound’
Wire: ‘Wire’
ReturnsA string according to the geometry type
Return typeLiteral[‘Vertex’, ‘Wire’, ‘Shell’, ‘Solid’, ‘Compound’, ‘PLANE’, ‘CYLINDER’, ‘CONE’, ‘SPHERE’, ‘TORUS’, ‘BEZIER’, ‘BSPLINE’, ‘REVOLUTION’, ‘EXTRUSION’, ‘OFFSET’, ‘OTHER’, ‘LINE’, ‘CIRCLE’, ‘ELLIPSE’, ‘HYPERBOLA’, ‘PARABOLA’]
hashCode()→ int[source]Returns a hashed value denoting this shape. It is computed from the TShape and the Location. The Orientation is not used.
Return typeint
classmethodimportBrep(f: Union[str, BytesIO])→ Shape[source]Import shape from a BREP file
Parametersf (Union[str, BytesIO]) –
Return typeShape
intersect(toIntersect: Shape, tol: Optional[float] = None)→ Shape[source]Intersection of the positional arguments and this Shape.
Parameters- *tol** (Optional[float]) – Fuzzy mode tolerance

• toIntersect (Shape) –

Return typeShape
isEqual(other: Shape)→ bool[source]Returns True if two shapes are equal, i.e. if they share the same TShape with the same Locations and Orientations. Also see isSame().
Parametersother (Shape) –
Return typebool
isNull()→ bool[source]Returns true if this shape is null. In other words, it references no underlying shape with the potential to be given a location and an orientation.
Return typebool
isSame(other: Shape)→ bool[source]Returns True if other and this shape are same, i.e. if they share the same TShape with the same Locations. Orientations may differ. Also see isEqual()
Parametersother (Shape) –
Return typebool
isValid()→ bool[source]Returns True if no defect is detected on the shape S or any of its subshapes. See the OCCT docs on BRepCheck_Analyzer::IsValid for a full description of what is checked.
Return typebool
locate(loc: Location)→ T[source]Apply a location in absolute sense to self
Parameters- self (T) –

• loc (Location) –

Return typeT
located(loc: Location)→ T[source]Apply a location in absolute sense to a copy of self
Parameters- self (T) –

• loc (Location) –

Return typeT
location()→ Location[source]Return the current location
Return typeLocation
staticmatrixOfInertia(obj: Shape)→ List[List[float]][[source]](https://cadquery.readthedocs.io/en/latest/_modules/cadquery/occ_impl/shapes.html#Shape.matrixOfInertia)Calculates the matrix of inertia of an object. :param obj: Compute the matrix of inertia of this object
Parametersobj (Shape) –
Return typeList[List[float]]
mesh(tolerance: float, angularTolerance: float = 0.1)[source]Generate triangulation if none exists.
Parameters- tolerance (float) –

• angularTolerance (float) –

mirror(mirrorPlane: Union[Literal['XY', 'YX', 'XZ', 'ZX', 'YZ', 'ZY'], Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]] = 'XY', basePointVector: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]] = (0, 0, 0))→ Shape[source]Applies a mirror transform to this Shape. Does not duplicate objects about the plane.
Parameters- mirrorPlane (Union[Literal['XY', 'YX', 'XZ', 'ZX', 'YZ', 'ZY'], Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – The direction of the plane to mirror about - one of ‘XY’, ‘XZ’ or ‘YZ’

• basePointVector (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – The origin of the plane to mirror about

ReturnsThe mirrored shape
Return typeShape
move(loc: Location)→ T[source]Apply a location in relative sense (i.e. update current location) to self
Parameters- self (T) –

• loc (Location) –

Return typeT
moved(loc: Location)→ T[source]Apply a location in relative sense (i.e. update current location) to a copy of self
Parameters- self (T) –

• loc (Location) –

Return typeT
rotate(startVector: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], endVector: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], angleDegrees: float)→ T[source]Rotates a shape around an axis.
Parameters- self (T) –

• startVector (either a 3-tuple or a Vector) – start point of rotation axis

• endVector (either a 3-tuple or a Vector) – end point of rotation axis

• angleDegrees (float) – angle to rotate, in degrees

Returnsa copy of the shape, rotated
Return typeT
scale(factor: float)→ Shape[source]Scales this shape through a transformation.
Parametersfactor (float) –
Return typeShape
shells(selector: Optional[Union[Selector, str]] = None)→ Shape[source]Select shells.
Parametersselector (Optional[Union[Selector, str]]) –
Return typeShape
siblings(shape: Shape, kind: Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound'], level: int = 1)→ Compound[source]Iterate over siblings, i.e. shapes within shape that share subshapes of kind with self.
Parameters- shape (Shape) –

• kind (Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound']) –

• level (int) –

Return typeCompound
solids(selector: Optional[Union[Selector, str]] = None)→ Shape[source]Select solids.
Parametersselector (Optional[Union[Selector, str]]) –
Return typeShape
split(splitters: Shape)→ Shape[source]Split this shape with the positional arguments.
Parameters*splitters* (Shape) –
Return typeShape
toSplines(degree: int = 3, tolerance: float = 0.001, nurbs: bool = False)→ T[source]Approximate shape with b-splines of the specified degree.
Parameters- *self** (T) –

• degree (int) – Maximum degree.

• tolerance (float) – Approximation tolerance.

• nurbs (bool) – Use rational splines.

Return typeT
toVtkPolyData(tolerance: Optional[float] = None, angularTolerance: Optional[float] = None, normals: bool = False)→ vtkPolyData[source]Convert shape to vtkPolyData
Parameters- tolerance (Optional[float]) –

• angularTolerance (Optional[float]) –

• normals (bool) –

Return typevtkPolyData
transformGeometry(tMatrix: Matrix)→ Shape[source]Transforms this shape by tMatrix.
WARNING: transformGeometry will sometimes convert lines and circles to splines, but it also has the ability to handle skew and stretching transformations.
If your transformation is only translation and rotation, it is safer to use transformShape(), which doesn’t change the underlying type of the geometry, but cannot handle skew transformations.
ParameterstMatrix (Matrix) – The transformation matrix
Returnsa copy of the object, but with geometry transformed instead of just rotated.
Return typeShape
transformShape(tMatrix: Matrix)→ Shape[source]Transforms this Shape by tMatrix. Also see transformGeometry().
ParameterstMatrix (Matrix) – The transformation matrix
Returnsa copy of the object, transformed by the provided matrix, with all objects keeping their type
Return typeShape
translate(vector: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])→ T[source]Translates this shape through a transformation.
Parameters- self (T) –

• vector (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

Return typeT
vertices(selector: Optional[Union[Selector, str]] = None)→ Shape[source]Select vertices.
Parametersselector (Optional[Union[Selector, str]]) –
Return typeShape
wires(selector: Optional[Union[Selector, str]] = None)→ Shape[source]Select wires.
Parametersselector (Optional[Union[Selector, str]]) –
Return typeShape
classcadquery.Shell(obj: TopoDS_Shape)[source]Bases: Shape
the outer boundary of a surface
Parametersobj (TopoDS_Shape) –
classmethodmakeShell(listOfFaces: Iterable[Face])→ Shell[source]Makes a shell from faces.
ParameterslistOfFaces (Iterable[Face]) –
Return typeShell
classcadquery.Sketch(parent: ~typing.Any = None, locs: ~typing.Iterable[~cadquery.occ_impl.geom.Location] = (<cadquery.occ_impl.geom.Location object>, ))[source]Bases: object
2D sketch. Supports faces, edges and edges with constraints based construction.
Parameters- parent (Any) –

• locs (List[Location]) –

init(parent: ~typing.Any = None, locs: ~typing.Iterable[~cadquery.occ_impl.geom.Location] = (<cadquery.occ_impl.geom.Location object>, ))[source]Construct an empty sketch.
Parameters- self (T) –

• parent (Any) –

• locs (Iterable[Location]) –

iter()→ Iterator[Face][source]Iterate over faces-locations combinations.
Return typeIterator[Face]
weakreflist of weak references to the object (if defined)
arc(p1: Union[Vector, Tuple[Union[int, float], Union[int, float]]], p2: Union[Vector, Tuple[Union[int, float], Union[int, float]]], p3: Union[Vector, Tuple[Union[int, float], Union[int, float]]], tag: Optional[str] = None, forConstruction: bool = False)→ T[source]arc(p2: Union[Vector, Tuple[Union[int, float], Union[int, float]]], p3: Union[Vector, Tuple[Union[int, float], Union[int, float]]], tag: Optional[str] = None, forConstruction: bool = False)→ Tarc(c: Union[Vector, Tuple[Union[int, float], Union[int, float]]], r: Union[int, float], a: Union[int, float], da: Union[int, float], tag: Optional[str] = None, forConstruction: bool = False)→ TConstruct an arc.
Parameters- self (T) –

• p1 (Union[Vector, Tuple[Union[int, float], Union[int, float]]]) –

• p2 (Union[Vector, Tuple[Union[int, float], Union[int, float]]]) –

• p3 (Union[Vector, Tuple[Union[int, float], Union[int, float]]]) –

• tag (Optional[str]) –

• forConstruction (bool) –

Return typeT
assemble(mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None)→ T[source]Assemble edges into faces.
Parameters- self (T) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

Return typeT
chamfer(d: Union[int, float])→ T[source]Add a chamfer based on current selection.
Parameters- self (T) –

• d (Union[int, float]) –

Return typeT
circle(r: Union[int, float], mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None)→ T[source]Construct a circular face.
Parameters- self (T) –

• r (Union[int, float]) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

Return typeT
clean()→ T[source]Remove internal wires.
Parametersself (T) –
Return typeT
close(tag: Optional[str] = None)→ T[source]Connect last edge to the first one.
Parameters- self (T) –

• tag (Optional[str]) –

Return typeT
constrain(tag1: str, tag2: str, constraint: Literal['Fixed', 'FixedPoint', 'Coincident', 'Angle', 'Length', 'Distance', 'Radius', 'Orientation', 'ArcAngle'], arg: Any)→ T[source]constrain(tag: str, constraint: Literal['Fixed', 'FixedPoint', 'Coincident', 'Angle', 'Length', 'Distance', 'Radius', 'Orientation', 'ArcAngle'], arg: Any)→ TAdd a constraint.
Parameters- self (T) –

• tag (str) –

• constraint (Literal['Fixed', 'FixedPoint', 'Coincident', 'Angle', 'Length', 'Distance', 'Radius', 'Orientation', 'ArcAngle']) –

• arg (Any) –

Return typeT
copy()→ T[source]Create a partial copy of the sketch.
Parametersself (T) –
Return typeT
delete()→ T[source]Delete selected object.
Parametersself (T) –
Return typeT
distribute(n: int, start: Union[int, float] = 0, stop: Union[int, float] = 1, rotate: bool = True)→ T[source]Distribute locations along selected edges or wires.
Parameters- self (T) –

• n (int) –

• start (Union[int, float]) –

• stop (Union[int, float]) –

• rotate (bool) –

Return typeT
each(callback: Callable[[Location], Union[Face, Sketch, Compound]], mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None, ignore_selection: bool = False)→ T[source]Apply a callback on all applicable entities.
Parameters- self (T) –

• callback (Callable[[Location], Union[Face, Sketch, Compound]]) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

• ignore_selection (bool) –

Return typeT
edge(val: Edge, tag: Optional[str] = None, forConstruction: bool = False)→ T[source]Add an edge to the sketch.
Parameters- self (T) –

• val (Edge) –

• tag (Optional[str]) –

• forConstruction (bool) –

Return typeT
edges(s: Optional[Union[str, Selector]] = None, tag: Optional[str] = None)→ T[source]Select edges.
Parameters- self (T) –

• s (Optional[Union[str, Selector]]) –

• tag (Optional[str]) –

Return typeT
ellipse(a1: Union[int, float], a2: Union[int, float], angle: Union[int, float] = 0, mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None)→ T[source]Construct an elliptical face.
Parameters- self (T) –

• a1 (Union[int, float]) –

• a2 (Union[int, float]) –

• angle (Union[int, float]) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

Return typeT
face(b: Union[Wire, Iterable[Edge], Compound, T], angle: Union[int, float] = 0, mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None, ignore_selection: bool = False)→ T[source]Construct a face from a wire or edges.
Parameters- self (T) –

• b (Union[Wire, Iterable[Edge], Compound, T]) –

• angle (Union[int, float]) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

• ignore_selection (bool) –

Return typeT
faces(s: Optional[Union[str, Selector]] = None, tag: Optional[str] = None)→ T[source]Select faces.
Parameters- self (T) –

• s (Optional[Union[str, Selector]]) –

• tag (Optional[str]) –

Return typeT
fillet(d: Union[int, float])→ T[source]Add a fillet based on current selection.
Parameters- self (T) –

• d (Union[int, float]) –

Return typeT
finalize()→ Any[source]Finish sketch construction and return the parent.
Return typeAny
hull(mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None)→ T[source]Generate a convex hull from current selection or all objects.
Parameters- self (T) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

Return typeT
importDXF(filename: str, tol: float = 1e-06, exclude: List[str] = [], include: List[str] = [], angle: Union[int, float] = 0, mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None)→ T[source]Import a DXF file and construct face(s)
Parameters- self (T) –

• filename (str) –

• tol (float) –

• exclude (List[str]) –

• include (List[str]) –

• angle (Union[int, float]) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

Return typeT
located(loc: Location)→ T[source]Create a partial copy of the sketch with a new location.
Parameters- self (T) –

• loc (Location) –

Return typeT
moved(loc: Location)→ T[source]Create a partial copy of the sketch with moved _faces.
Parameters- self (T) –

• loc (Location) –

Return typeT
offset(d: Union[int, float], mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None)→ T[source]Offset selected wires or edges.
Parameters- self (T) –

• d (Union[int, float]) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

Return typeT
parray(r: Union[int, float], a1: Union[int, float], da: Union[int, float], n: int, rotate: bool = True)→ T[source]Generate a polar array of locations.
Parameters- self (T) –

• r (Union[int, float]) –

• a1 (Union[int, float]) –

• da (Union[int, float]) –

• n (int) –

• rotate (bool) –

Return typeT
polygon(pts: Iterable[Union[Vector, Tuple[Union[int, float], Union[int, float]]]], angle: Union[int, float] = 0, mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None)→ T[source]Construct a polygonal face.
Parameters- self (T) –

• pts (Iterable[Union[Vector, Tuple[Union[int, float], Union[int, float]]]]) –

• angle (Union[int, float]) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

Return typeT
push(locs: Iterable[Union[Location, Vector, Tuple[Union[int, float], Union[int, float]]]], tag: Optional[str] = None)→ T[source]Set current selection to given locations or points.
Parameters- self (T) –

• locs (Iterable[Union[Location, Vector, Tuple[Union[int, float], Union[int, float]]]]) –

• tag (Optional[str]) –

Return typeT
rarray(xs: Union[int, float], ys: Union[int, float], nx: int, ny: int)→ T[source]Generate a rectangular array of locations.
Parameters- self (T) –

• xs (Union[int, float]) –

• ys (Union[int, float]) –

• nx (int) –

• ny (int) –

Return typeT
rect(w: Union[int, float], h: Union[int, float], angle: Union[int, float] = 0, mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None)→ T[source]Construct a rectangular face.
Parameters- self (T) –

• w (Union[int, float]) –

• h (Union[int, float]) –

• angle (Union[int, float]) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

Return typeT
regularPolygon(r: Union[int, float], n: int, angle: Union[int, float] = 0, mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None)→ T[source]Construct a regular polygonal face.
Parameters- self (T) –

• r (Union[int, float]) –

• n (int) –

• angle (Union[int, float]) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

Return typeT
reset()→ T[source]Reset current selection.
Parametersself (T) –
Return typeT
segment(p1: Union[Vector, Tuple[Union[int, float], Union[int, float]]], p2: Union[Vector, Tuple[Union[int, float], Union[int, float]]], tag: Optional[str] = None, forConstruction: bool = False)→ T[source]segment(l: Union[int, float], a: Union[int, float], tag: Optional[str] = None, forConstruction: bool = False)→ Tsegment(p2: Union[Vector, Tuple[Union[int, float], Union[int, float]]], tag: Optional[str] = None, forConstruction: bool = False)→ TConstruct a segment.
Parameters- self (T) –

• p1 (Union[Vector, Tuple[Union[int, float], Union[int, float]]]) –

• p2 (Union[Vector, Tuple[Union[int, float], Union[int, float]]]) –

• tag (Optional[str]) –

• forConstruction (bool) –

Return typeT
select(tags: str)→ T[source]Select based on tags.
Parameters- *self** (T) –

• tags (str) –

Return typeT
slot(w: Union[int, float], h: Union[int, float], angle: Union[int, float] = 0, mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None)→ T[source]Construct a slot-shaped face.
Parameters- self (T) –

• w (Union[int, float]) –

• h (Union[int, float]) –

• angle (Union[int, float]) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

Return typeT
solve()→ T[source]Solve current constraints and update edge positions.
Parametersself (T) –
Return typeT
spline(pts: Iterable[Union[Vector, Tuple[Union[int, float], Union[int, float]]]], tangents: Optional[Iterable[Union[Vector, Tuple[Union[int, float], Union[int, float]]]]], periodic: bool, tag: Optional[str] = None, forConstruction: bool = False)→ T[source]spline(pts: Iterable[Union[Vector, Tuple[Union[int, float], Union[int, float]]]], tag: Optional[str] = None, forConstruction: bool = False)→ TConstruct a spline edge.
Parameters- self (T) –

• pts (Iterable[Union[Vector, Tuple[Union[int, float], Union[int, float]]]]) –

• tangents (Optional[Iterable[Union[Vector, Tuple[Union[int, float], Union[int, float]]]]]) –

• periodic (bool) –

• tag (Optional[str]) –

• forConstruction (bool) –

Return typeT
tag(tag: str)→ T[source]Tag current selection.
Parameters- self (T) –

• tag (str) –

Return typeT
trapezoid(w: Union[int, float], h: Union[int, float], a1: Union[int, float], a2: Optional[float] = None, angle: Union[int, float] = 0, mode: Literal['a', 's', 'i', 'c'] = 'a', tag: Optional[str] = None)→ T[source]Construct a trapezoidal face.
Parameters- self (T) –

• w (Union[int, float]) –

• h (Union[int, float]) –

• a1 (Union[int, float]) –

• a2 (Optional[float]) –

• angle (Union[int, float]) –

• mode (Literal['a', 's', 'i', 'c']) –

• tag (Optional[str]) –

Return typeT
val()→ Union[Shape, Location][source]Return the first selected item or Location().
Parametersself (T) –
Return typeUnion[Shape, Location]
vals()→ List[Union[Shape, Location]][source]Return the list of selected items.
Parametersself (T) –
Return typeList[Union[Shape, Location]]
vertices(s: Optional[Union[str, Selector]] = None, tag: Optional[str] = None)→ T[source]Select vertices.
Parameters- self (T) –

• s (Optional[Union[str, Selector]]) –

• tag (Optional[str]) –

Return typeT
wires(s: Optional[Union[str, Selector]] = None, tag: Optional[str] = None)→ T[source]Select wires.
Parameters- self (T) –

• s (Optional[Union[str, Selector]]) –

• tag (Optional[str]) –

Return typeT
classcadquery.Solid(obj: TopoDS_Shape)[source]Bases: Shape, Mixin3D
a single solid
Parametersobj (TopoDS_Shape) –
classmethodextrudeLinear(face: Face, vecNormal: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], taper: Union[float, int] = 0)→ Solid[source]classmethodextrudeLinear(outerWire: Wire, innerWires: List[Wire], vecNormal: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], taper: Union[float, int] = 0)→ SolidAttempt to extrude the list of wires into a prismatic solid in the provided direction
Parameters- outerWire (Wire) – the outermost wire

• innerWires (List[Wire]) – a list of inner wires

• vecNormal (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – a vector along which to extrude the wires

• taper (Union[float, int]) – taper angle, default=0

Returnsa Solid object
Return typeSolid
The wires must not intersect
Extruding wires is very non-trivial. Nested wires imply very different geometry, and there are many geometries that are invalid. In general, the following conditions must be met:

• all wires must be closed

• there cannot be any intersecting or self-intersecting wires

• wires must be listed from outside in

• more than one levels of nesting is not supported reliably

This method will attempt to sort the wires, but there is much work remaining to make this method reliable.
classmethodextrudeLinearWithRotation(outerWire: Wire, innerWires: List[Wire], vecCenter: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], vecNormal: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], angleDegrees: Union[float, int])→ Solid[source]classmethodextrudeLinearWithRotation(face: Face, vecCenter: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], vecNormal: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], angleDegrees: Union[float, int])→ SolidCreates a ‘twisted prism’ by extruding, while simultaneously rotating around the extrusion vector.
Though the signature may appear to be similar enough to extrudeLinear to merit combining them, the construction methods used here are different enough that they should be separate.
At a high level, the steps followed are:

1. accept a set of wires

2. create another set of wires like this one, but which are transformed and rotated

3. create a ruledSurface between the sets of wires

4. create a shell and compute the resulting object

Parameters- outerWire (Wire) – the outermost wire

• innerWires (List[Wire]) – a list of inner wires

• vecCenter (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – the center point about which to rotate. the axis of rotation is defined by vecNormal, located at vecCenter.

• vecNormal (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – a vector along which to extrude the wires

• angleDegrees (Union[float, int]) – the angle to rotate through while extruding

Returnsa Solid object
Return typeSolid
classmethodinterpPlate(surf_edges, surf_pts, thickness, degree=3, nbPtsOnCur=15, nbIter=2, anisotropy=False, tol2d=1e-05, tol3d=0.0001, tolAng=0.01, tolCurv=0.1, maxDeg=8, maxSegments=9)→ Union[Solid, Face][source]Returns a plate surface that is ‘thickness’ thick, enclosed by ‘surf_edge_pts’ points, and going through ‘surf_pts’ points.
Parameters- surf_edges – list of [x,y,z] float ordered coordinates or list of ordered or unordered wires

• surf_pts – list of [x,y,z] float coordinates (uses only edges if [])

• thickness – thickness may be negative or positive depending on direction, (returns 2D surface if 0)

• degree – >=2

• nbPtsOnCur – number of points on curve >= 15

• nbIter – number of iterations >= 2

• anisotropy – bool Anisotropy

• tol2d – 2D tolerance >0

• tol3d – 3D tolerance >0

• tolAng – angular tolerance

• tolCurv – tolerance for curvature >0

• maxDeg – highest polynomial degree >= 2

• maxSegments – greatest number of segments >= 2

Return typeUnion[Solid, Face]
staticisSolid(obj: Shape)→ bool[source]Returns true if the object is a solid, false otherwise
Parametersobj (Shape) –
Return typebool
classmethodmakeBox(length,width,height,[pnt,dir]) -- Make a box located in pnt with the dimensions (length,width,height)[source]By default pnt=Vector(0,0,0) and dir=Vector(0,0,1)
Parameters- length (float) –

• width (float) –

• height (float) –

• pnt (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• dir (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

Return typeSolid
classmethodmakeCone(radius1: float, radius2: float, height: float, pnt: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 0.0), dir: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 1.0), angleDegrees: float = 360)→ Solid[source]Make a cone with given radii and height By default pnt=Vector(0,0,0), dir=Vector(0,0,1) and angle=360
Parameters- radius1 (float) –

• radius2 (float) –

• height (float) –

• pnt (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• dir (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• angleDegrees (float) –

Return typeSolid
classmethodmakeCylinder(radius: float, height: float, pnt: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 0.0), dir: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 1.0), angleDegrees: float = 360)→ Solid[source]makeCylinder(radius,height,[pnt,dir,angle]) – Make a cylinder with a given radius and height By default pnt=Vector(0,0,0),dir=Vector(0,0,1) and angle=360
Parameters- radius (float) –

• height (float) –

• pnt (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• dir (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• angleDegrees (float) –

Return typeSolid
classmethodmakeLoft(listOfWire: List[Wire], ruled: bool = False)→ Solid[source]makes a loft from a list of wires The wires will be converted into faces when possible– it is presumed that nobody ever actually wants to make an infinitely thin shell for a real FreeCADPart.
Parameters- listOfWire (List[Wire]) –

• ruled (bool) –

Return typeSolid
classmethodmakeSolid(shell: Shell)→ Solid[source]Makes a solid from a single shell.
Parametersshell (Shell) –
Return typeSolid
classmethodmakeSphere(radius: float, pnt: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 0.0), dir: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 1.0), angleDegrees1: float = 0, angleDegrees2: float = 90, angleDegrees3: float = 360)→ Shape[source]Make a sphere with a given radius By default pnt=Vector(0,0,0), dir=Vector(0,0,1), angle1=0, angle2=90 and angle3=360
Parameters- radius (float) –

• pnt (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• dir (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• angleDegrees1 (float) –

• angleDegrees2 (float) –

• angleDegrees3 (float) –

Return typeShape
classmethodmakeTorus(radius1: float, radius2: float, pnt: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 0.0), dir: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 1.0), angleDegrees1: float = 0, angleDegrees2: float = 360)→ Solid[source]makeTorus(radius1,radius2,[pnt,dir,angle1,angle2,angle]) – Make a torus with a given radii and angles By default pnt=Vector(0,0,0),dir=Vector(0,0,1),angle1=0 ,angle1=360 and angle=360
Parameters- radius1 (float) –

• radius2 (float) –

• pnt (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• dir (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• angleDegrees1 (float) –

• angleDegrees2 (float) –

Return typeSolid
classmethodmakeWedge(dx: float, dy: float, dz: float, xmin: float, zmin: float, xmax: float, zmax: float, pnt: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 0.0), dir: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 1.0))→ Solid[source]Make a wedge located in pnt By default pnt=Vector(0,0,0) and dir=Vector(0,0,1)
Parameters- dx (float) –

• dy (float) –

• dz (float) –

• xmin (float) –

• zmin (float) –

• xmax (float) –

• zmax (float) –

• pnt (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• dir (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

Return typeSolid
classmethodrevolve(outerWire: Wire, innerWires: List[Wire], angleDegrees: Union[float, int], axisStart: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], axisEnd: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])→ Solid[source]classmethodrevolve(face: Face, angleDegrees: Union[float, int], axisStart: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], axisEnd: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])→ SolidAttempt to revolve the list of wires into a solid in the provided direction
Parameters- outerWire (Wire) – the outermost wire

• innerWires (List[Wire]) – a list of inner wires

• angleDegrees (float, anything less than 360 degrees will leave the shape open) – the angle to revolve through.

• axisStart (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – the start point of the axis of rotation

• axisEnd (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – the end point of the axis of rotation

Returnsa Solid object
Return typeSolid
The wires must not intersect

• all wires must be closed

• there cannot be any intersecting or self-intersecting wires

• wires must be listed from outside in

• more than one levels of nesting is not supported reliably

• the wire(s) that you’re revolving cannot be centered

This method will attempt to sort the wires, but there is much work remaining to make this method reliable.
classmethodsweep(outerWire: Wire, innerWires: List[Wire], path: Union[Wire, Edge], makeSolid: bool = True, isFrenet: bool = False, mode: Optional[Union[Vector, Wire, Edge]] = None, transitionMode: Literal['transformed', 'round', 'right'] = 'transformed')→ Shape[source]classmethodsweep(face: Face, path: Union[Wire, Edge], makeSolid: bool = True, isFrenet: bool = False, mode: Optional[Union[Vector, Wire, Edge]] = None, transitionMode: Literal['transformed', 'round', 'right'] = 'transformed')→ ShapeAttempt to sweep the list of wires into a prismatic solid along the provided path
Parameters- outerWire (Wire) – the outermost wire

• innerWires (List[Wire]) – a list of inner wires

• path (Union[Wire, Edge]) – The wire to sweep the face resulting from the wires over

• makeSolid (bool) – return Solid or Shell (default True)

• isFrenet (bool) – Frenet mode (default False)

• mode (Optional[Union[Vector, Wire, Edge]]) – additional sweep mode parameters

• transitionMode (Literal['transformed', 'round', 'right']) – handling of profile orientation at C1 path discontinuities. Possible values are {‘transformed’,’round’, ‘right’} (default: ‘right’).

Returnsa Solid object
Return typeShape
classmethodsweep_multi(profiles: Iterable[Union[Wire, Face]], path: Union[Wire, Edge], makeSolid: bool = True, isFrenet: bool = False, mode: Optional[Union[Vector, Wire, Edge]] = None)→ Solid[source]Multi section sweep. Only single outer profile per section is allowed.
Parameters- profiles (Iterable[Union[Wire, Face]]) – list of profiles

• path (Union[Wire, Edge]) – The wire to sweep the face resulting from the wires over

• mode (Optional[Union[Vector, Wire, Edge]]) – additional sweep mode parameters.

• makeSolid (bool) –

• isFrenet (bool) –

Returnsa Solid object
Return typeSolid
classcadquery.StringSyntaxSelector(selectorString)[source]Bases: Selector
Filter lists objects using a simple string syntax. All of the filters available in the string syntax are also available ( usually with more functionality ) through the creation of full-fledged selector objects. see Selector and its subclasses
Filtering works differently depending on the type of object list being filtered.
ParametersselectorString – A two-part selector string, [selector][axis]
Returnsobjects that match the specified selector
Modifiers are ('|','+','-','<','>','%')

|parallel to ( same as ParallelDirSelector ). Can return multiple objects.

perpendicular to (same as PerpendicularDirSelector )

+positive direction (same as DirectionSelector )
-negative direction (same as DirectionSelector )

maximize (same as DirectionMinMaxSelector with directionMax=True)
<minimize (same as DirectionMinMaxSelector with directionMax=False )
%curve/surface type (same as TypeSelector)

axisStrings are: X,Y,Z,XY,YZ,XZ or (x,y,z) which defines an arbitrary direction
It is possible to combine simple selectors together using logical operations. The following operations are supported

andLogical AND, e.g. >X and >Y
orLogical OR, e.g. |X or |Y
notLogical NOT, e.g. not #XY
exc(ept)Set difference (equivalent to AND NOT): |X exc >Z

Finally, it is also possible to use even more complex expressions with nesting and arbitrary number of terms, e.g.

(not >X[0] and #XY) or >XY[0]

Selectors are a complex topic: see Selectors Reference for more information
init(selectorString)[source]Feed the input string through the parser and construct an relevant complex selector object
filter(objectList: Sequence[Shape])[source]Filter give object list through th already constructed complex selector object
ParametersobjectList (Sequence[Shape]) –
classcadquery.TypeSelector(typeString: str)[source]Bases: Selector
Selects objects having the prescribed geometry type.
Applicability:Faces: PLANE, CYLINDER, CONE, SPHERE, TORUS, BEZIER, BSPLINE, REVOLUTION, EXTRUSION, OFFSET, OTHER Edges: LINE, CIRCLE, ELLIPSE, HYPERBOLA, PARABOLA, BEZIER, BSPLINE, OFFSET, OTHER
You can use the string selector syntax. For example this:

CQ(aCube).faces(TypeSelector("PLANE"))

will select 6 faces, and is equivalent to:

CQ(aCube).faces("%PLANE")

ParameterstypeString (str) –
init(typeString: str)[source]ParameterstypeString (str) –
filter(objectList: Sequence[Shape])→ List[Shape][[source]](cadquery.readthedocs...)Filter the provided list.
The default implementation returns the original list unfiltered.
ParametersobjectList (list of OCCT primitives) – list to filter
Returnsfiltered list
Return typeList[Shape]
classcadquery.Vector(x: float, y: float, z: float)[source]classcadquery.Vector(x: float, y: float)classcadquery.Vector(v: Vector)classcadquery.Vector(v: Sequence[float])classcadquery.Vector(v: Union[gp_Vec, gp_Pnt, gp_Dir, gp_XYZ])classcadquery.VectorBases: object
Create a 3-dimensional vector
Parametersargs – a 3D vector, with x-y-z parts.
you can either provide:- nothing (in which case the null vector is return)

• a gp_Vec

• a vector ( in which case it is copied )

• a 3-tuple

• a 2-tuple (z assumed to be 0)

• three float values: x, y, and z

• two float values: x,y

Center()→ Vector[source]Return the vector itself
The center of myself is myself. Provided so that vectors, vertices, and other shapes all support a common interface, when Center() is requested for all objects on the stack.
Return typeVector
eq(other: Vector)→ bool[source]Return self==value.
Parametersother (Vector) –
Return typebool
hash= Noneinit(x: float, y: float, z: float)→ None[source]init(x: float, y: float)→ None__init__(v: Vector)→ None__init__(v: Sequence[float])→ None__init__(v: Union[gp_Vec, gp_Pnt, gp_Dir, gp_XYZ])→ None__init__()→ None__repr__()→ str[source]Return repr(self).
Return typestr
str()→ str[source]Return str(self).
Return typestr
weakreflist of weak references to the object (if defined)
multiply(scale: float)→ Vector[source]Return a copy multiplied by the provided scalar
Parametersscale (float) –
Return typeVector
normalized()→ Vector[source]Return a normalized version of this vector
Return typeVector
projectToLine(line: Vector)→ Vector[source]Returns a new vector equal to the projection of this Vector onto the line represented by Vector <line>
Parameters- args – Vector

• line (Vector) –

Return typeVector
Returns the projected vector.
projectToPlane(plane: Plane)→ Vector[source]Vector is projected onto the plane provided as input.
Parameters- args – Plane object

• plane (Plane) –

Return typeVector
Returns the projected vector.
classcadquery.Vertex(obj: TopoDS_Shape, forConstruction: bool = False)[source]Bases: Shape
A Single Point in Space
Parameters- obj (TopoDS_Shape) –

• forConstruction (bool) –

Center()→ Vector[source]The center of a vertex is itself!
Return typeVector
init(obj: TopoDS_Shape, forConstruction: bool = False)[source]Create a vertex
Parameters- obj (TopoDS_Shape) –

• forConstruction (bool) –

classcadquery.Wire(obj: TopoDS_Shape)[source]Bases: Shape, Mixin1D
A series of connected, ordered Edges, that typically bounds a Face
Parametersobj (TopoDS_Shape) –
iter()→ Iterator[Edge][source]Iterate over edges in an ordered way.
Return typeIterator[Edge]
classmethodassembleEdges(listOfEdges: Iterable[Edge])→ Wire[source]Attempts to build a wire that consists of the edges in the provided list
Parameters- cls –

• listOfEdges (Iterable[Edge]) – a list of Edge objects. The edges are not to be consecutive.

Returnsa wire with the edges assembled
Return typeWire
BRepBuilderAPI_MakeWire::Error() values:

• BRepBuilderAPI_WireDone = 0

• BRepBuilderAPI_EmptyWire = 1

• BRepBuilderAPI_DisconnectedWire = 2

• BRepBuilderAPI_NonManifoldWire = 3

chamfer2D(d: float, vertices: Iterable[Vertex])→ Wire[source]Apply 2D chamfer to a wire
Parameters- d (float) –

• vertices (Iterable[Vertex]) –

Return typeWire
close()→ Wire[source]Close a Wire
Return typeWire
classmethodcombine(listOfWires: Iterable[Union[Wire, Edge]], tol: float = 1e-09)→ List[Wire][source]Attempt to combine a list of wires and edges into a new wire.
Parameters- cls –

• listOfWires (Iterable[Union[Wire, Edge]]) –

• tol (float) – default 1e-9

ReturnsList[Wire]
Return typeList[Wire]
fillet2D(radius: float, vertices: Iterable[Vertex])→ Wire[source]Apply 2D fillet to a wire
Parameters- radius (float) –

• vertices (Iterable[Vertex]) –

Return typeWire
classmethodmakeCircle(radius: float, center: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], normal: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]])→ Wire[source]Makes a Circle centered at the provided point, having normal in the provided direction
Parameters- radius (float) – floating point radius of the circle, must be > 0

• center (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – vector representing the center of the circle

• normal (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – vector representing the direction of the plane the circle should lie in

Return typeWire
classmethodmakeEllipse(x_radius: float, y_radius: float, center: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], normal: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], xDir: Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]], angle1: float = 360.0, angle2: float = 360.0, rotation_angle: float = 0.0, closed: bool = True)→ Wire[source]Makes an Ellipse centered at the provided point, having normal in the provided direction
Parameters- x_radius (float) – floating point major radius of the ellipse (x-axis), must be > 0

• y_radius (float) – floating point minor radius of the ellipse (y-axis), must be > 0

• center (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – vector representing the center of the circle

• normal (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) – vector representing the direction of the plane the circle should lie in

• angle1 (float) – start angle of arc

• angle2 (float) – end angle of arc

• rotation_angle (float) – angle to rotate the created ellipse / arc

• xDir (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• closed (bool) –

Return typeWire
classmethodmakeHelix(pitch: float, height: float, radius: float, center: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 0.0), dir: ~typing.Union[~cadquery.occ_impl.geom.Vector, ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float]], ~typing.Tuple[~typing.Union[int, float], ~typing.Union[int, float], ~typing.Union[int, float]]] = Vector: (0.0, 0.0, 1.0), angle: float = 360.0, lefthand: bool = False)→ Wire[source]Make a helix with a given pitch, height and radius By default a cylindrical surface is used to create the helix. If the fourth parameter is set (the apex given in degree) a conical surface is used instead’
Parameters- pitch (float) –

• height (float) –

• radius (float) –

• center (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• dir (Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]) –

• angle (float) –

• lefthand (bool) –

Return typeWire
classmethodmakePolygon(listOfVertices: Iterable[Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]], forConstruction: bool = False, close: bool = False)→ Wire[source]Construct a polygonal wire from points.
Parameters- listOfVertices (Iterable[Union[Vector, Tuple[Union[int, float], Union[int, float]], Tuple[Union[int, float], Union[int, float], Union[int, float]]]]) –

• forConstruction (bool) –

• close (bool) –

Return typeWire
offset2D(d: float, kind: Literal['arc', 'intersection', 'tangent'] = 'arc')→ List[Wire][source]Offsets a planar wire
Parameters- d (float) –

• kind (Literal['arc', 'intersection', 'tangent']) –

Return typeList[Wire]
stitch(other: Wire)→ Wire[source]Attempt to stitch wires
Parametersother (Wire) –
Return typeWire
classcadquery.Workplane(obj: Union[Vector, Location, Shape, Sketch])[source]classcadquery.Workplane(inPlane: Union[Plane, str] = 'XY', origin: Union[Tuple[float, float], Tuple[float, float, float], Vector] = (0, 0, 0), obj: Optional[Union[Vector, Location, Shape, Sketch]] = None)Bases: object
Defines a coordinate system in space, in which 2D coordinates can be used.
Parameters- plane (a Plane object, or a string in (XY|YZ|XZ|front|back|top|bottom|left|right)) – the plane in which the workplane will be done

• origin (a 3-tuple in global coordinates, or None to default to the origin) – the desired origin of the new workplane

• obj (a CAD primitive, or None to use the centerpoint of the plane as the initial stack value.) – an object to use initially for the stack

RaisesValueError if the provided plane is not a plane, a valid named workplane
ReturnsA Workplane object, with coordinate system matching the supplied plane.
The most common use is:

s = Workplane("XY")

After creation, the stack contains a single point, the origin of the underlying plane, and the current point is on the origin.
Note
You can also create workplanes on the surface of existing faces using workplane()
add(toUnion: Union[Workplane, Solid, Compound])→ T[source]Syntactic sugar for union.
Notice that r = a + b is equivalent to r = a.union(b) and r = a | b.
Parameters- self (T) –

• toUnion (Union[Workplane, Solid, Compound]) –

Return typeT
and(toUnion: Union[Workplane, Solid, Compound])→ T[source]Syntactic sugar for intersect.
Notice that r = a & b is equivalent to r = a.intersect(b).
Example:

Box = Workplane("XY").box(1, 1, 1, centered=(False, False, False))
Sphere = Workplane("XY").sphere(1)
result = Box & Sphere

Parameters- self (T) –

• toUnion (Union[Workplane, Solid, Compound]) –

Return typeT
init(obj: Union[Vector, Location, Shape, Sketch])→ None[source]init(inPlane: Union[Plane, str] = 'XY', origin: Union[Tuple[float, float], Tuple[float, float, float], Vector] = (0, 0, 0), obj: Optional[Union[Vector, Location, Shape, Sketch]] = None)→ Nonemake a workplane from a particular plane
Parameters- inPlane (a Plane object, or a string in (XY|YZ|XZ|front|back|top|bottom|left|right)) – the plane in which the workplane will be done

• origin (a 3-tuple in global coordinates, or None to default to the origin) – the desired origin of the new workplane

• obj (a CAD primitive, or None to use the centerpoint of the plane as the initial stack value.) – an object to use initially for the stack

RaisesValueError if the provided plane is not a plane, or one of XY|YZ|XZ
ReturnsA Workplane object, with coordinate system matching the supplied plane.
The most common use is:

s = Workplane("XY")

After creation, the stack contains a single point, the origin of the underlying plane, and the current point is on the origin.
or(toUnion: Union[Workplane, Solid, Compound])→ T[source]Syntactic sugar for union.
Notice that r = a | b is equivalent to r = a.union(b) and r = a + b.
Example:

Box = Workplane("XY").box(1, 1, 1, centered=(False, False, False))
Sphere = Workplane("XY").sphere(1)
result = Box | Sphere

Parameters- self (T) –

• toUnion (Union[Workplane, Solid, Compound]) –

Return typeT
sub(toUnion: Union[Workplane, Solid, Compound])→ T[source]Syntactic sugar for cut.
Notice that r = a - b is equivalent to r = a.cut(b).
Example:

Box = Workplane("XY").box(1, 1, 1, centered=(False, False, False))
Sphere = Workplane("XY").sphere(1)
result = Box - Sphere

Parameters- self (T) –

• toUnion (Union[Workplane, Solid, Compound]) –

Return typeT
weakreflist of weak references to the object (if defined)
add(obj: Workplane)→ T[source]add(obj: Union[Vector, Location, Shape, Sketch])→ Tadd(obj: Iterable[Union[Vector, Location, Shape, Sketch]])→ TAdds an object or a list of objects to the stack
Parametersobj (a Workplane, CAD primitive, or list of CAD primitives) – an object to add
Returnsa Workplane with the requested operation performed
If a Workplane object, the values of that object’s stack are added. If a list of cad primitives, they are all added. If a single CAD primitive then it is added.
Used in rare cases when you need to combine the results of several CQ results into a single Workplane object.
all()→ List[T][[source]](cadquery.readthedocs...)Return a list of all CQ objects on the stack.
useful when you need to operate on the elements individually.
Contrast with vals, which returns the underlying objects for all of the items on the stack
Parametersself (T) –
Return typeList[T]
ancestors(kind: Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound'], tag: Optional[str] = None)→ T[source]Select topological ancestors.
Parameters- self (T) –

• kind (Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound']) – kind of ancestor, e.g. “Face” or “Edge”

• tag (Optional[str]) – if set, search the tagged object instead of self

Returnsa Workplane object whose stack contains selected ancestors.
Return typeT
box(length: float, width: float, height: float, centered: Union[bool, Tuple[bool, bool, bool]] = True, combine: Union[bool, Literal['cut', 'a', 's']] = True, clean: bool = True)→ T[source]Return a 3d box with specified dimensions for each object on the stack.
Parameters- self (T) –

• length (float) – box size in X direction

• width (float) – box size in Y direction

• height (float) – box size in Z direction

• centered (Union[bool, Tuple[bool, bool, bool]]) – If True, the box will be centered around the reference point. If False, the corner of the box will be on the reference point and it will extend in the positive x, y and z directions. Can also use a 3-tuple to specify centering along each axis.

• combine (Union[bool, Literal['cut', 'a', 's']]) – should the results be combined with other solids on the stack (and each other)?

• clean (bool) – call clean() afterwards to have a clean shape

Return typeT
One box is created for each item on the current stack. If no items are on the stack, one box using the current workplane center is created.
If combine is true, the result will be a single object on the stack. If a solid was found in the chain, the result is that solid with all boxes produced fused onto it otherwise, the result is the combination of all the produced boxes.
If combine is false, the result will be a list of the boxes produced.
Most often boxes form the basis for a part:

# make a single box with lower left corner at origin
s = Workplane().box(1, 2, 3, centered=False)

But sometimes it is useful to create an array of them:

# create 4 small square bumps on a larger base plate:
s = (
    Workplane()
    .box(4, 4, 0.5)
    .faces(">Z")
    .workplane()
    .rect(3, 3, forConstruction=True)
    .vertices()
    .box(0.25, 0.25, 0.25, combine=True)
)

cboreHole(diameter: float, cboreDiameter: float, cboreDepth: float, depth: Optional[float] = None, clean: bool = True)→ T[source]Makes a counterbored hole for each item on the stack.
Parameters- self (T) –

• diameter (float) – the diameter of the hole

• cboreDiameter (float) – the diameter of the cbore, must be greater than hole diameter

• cboreDepth (float > 0) – depth of the counterbore

• depth (float > 0 or None to drill thru the entire part) – the depth of the hole

• clean (bool) – call clean() afterwards to have a clean shape

Return typeT
The surface of the hole is at the current workplane plane.
One hole is created for each item on the stack. A very common use case is to use a construction rectangle to define the centers of a set of holes, like so:

s = (
    Workplane()
    .box(2, 4, 0.5)
    .faces(">Z")
    .workplane()
    .rect(1.5, 3.5, forConstruction=True)
    .vertices()
    .cboreHole(0.125, 0.25, 0.125, depth=None)
)

This sample creates a plate with a set of holes at the corners.
Plugin Note: this is one example of the power of plugins. Counterbored holes are quite time consuming to create, but are quite easily defined by users.
see cskHole() to make countersinks instead of counterbores
center(x: float, y: float)→ T[source]Shift local coordinates to the specified location.
The location is specified in terms of local coordinates.
Parameters- self (T) –

• x (float) – the new x location

• y (float) – the new y location

Returnsthe Workplane object, with the center adjusted.
Return typeT
The current point is set to the new center. This method is useful to adjust the center point after it has been created automatically on a face, but not where you’d like it to be.
In this example, we adjust the workplane center to be at the corner of a cube, instead of the center of a face, which is the default:

# this workplane is centered at x=0.5,y=0.5, the center of the upper face
s = Workplane().box(1, 1, 1).faces(">Z").workplane()

s = s.center(-0.5, -0.5)  # move the center to the corner
t = s.circle(0.25).extrude(0.2)
assert t.faces().size() == 9  # a cube with a cylindrical nub at the top right corner

The result is a cube with a round boss on the corner
chamfer(length: float, length2: Optional[float] = None)→ T[source]Chamfers a solid on the selected edges.
The edges on the stack are chamfered. The solid to which the edges belong must be in the parent chain of the selected edges.
Optional parameter length2 can be supplied with a different value than length for a chamfer that is shorter on one side longer on the other side.
Parameters- self (T) –

• length (float) – the length of the chamfer, must be greater than zero

• length2 (Optional[float]) – optional parameter for asymmetrical chamfer

Raises- ValueError – if at least one edge is not selected

• ValueError – if the solid containing the edge is not in the chain

ReturnsCQ object with the resulting solid selected.
Return typeT
This example will create a unit cube, with the top edges chamfered:

s = Workplane("XY").box(1, 1, 1).faces("+Z").chamfer(0.1)

This example will create chamfers longer on the sides:

s = Workplane("XY").box(1, 1, 1).faces("+Z").chamfer(0.2, 0.1)

circle(radius: float, forConstruction: bool = False)→ T[source]Make a circle for each item on the stack.
Parameters- self (T) –

• radius (float) – radius of the circle

• forConstruction (true if the wires are for reference, false if they are creating part geometry) – should the new wires be reference geometry only?

Returnsa new CQ object with the created wires on the stack
Return typeT
A common use case is to use a for-construction rectangle to define the centers of a hole pattern:

s = Workplane().rect(4.0, 4.0, forConstruction=True).vertices().circle(0.25)

Creates 4 circles at the corners of a square centered on the origin. Another common case is to use successive circle() calls to create concentric circles. This works because the center of a circle is its reference point:

s = Workplane().circle(2.0).circle(1.0)

Creates two concentric circles, which when extruded will form a ring.
Future Enhancements:better way to handle forConstruction project points not in the workplane plane onto the workplane plane
clean()→ T[source]Cleans the current solid by removing unwanted edges from the faces.
Normally you don’t have to call this function. It is automatically called after each related operation. You can disable this behavior with clean=False parameter if method has any. In some cases this can improve performance drastically but is generally dis-advised since it may break some operations such as fillet.
Note that in some cases where lots of solid operations are chained, clean() may actually improve performance since the shape is ‘simplified’ at each step and thus next operation is easier.
Also note that, due to limitation of the underlying engine, clean may fail to produce a clean output in some cases such as spherical faces.
Parametersself (T) –
Return typeT
close()→ T[source]End construction, and attempt to build a closed wire.
Returnsa CQ object with a completed wire on the stack, if possible.
Parametersself (T) –
Return typeT
After 2D (or 3D) drafting with methods such as lineTo, threePointArc, tangentArcPoint and polyline, it is necessary to convert the edges produced by these into one or more wires.
When a set of edges is closed, CadQuery assumes it is safe to build the group of edges into a wire. This example builds a simple triangular prism:

s = Workplane().lineTo(1, 0).lineTo(1, 1).close().extrude(0.2)

combine(clean: bool = True, glue: bool = False, tol: Optional[float] = None)→ T[source]Attempts to combine all of the items on the stack into a single item.
WARNING: all of the items must be of the same type!
Parameters- self (T) –

• clean (bool) – call clean() afterwards to have a clean shape

• glue (bool) – use a faster gluing mode for non-overlapping shapes (default False)

• tol (Optional[float]) – tolerance value for fuzzy bool operation mode (default None)

RaisesValueError if there are no items on the stack, or if they cannot be combined
Returnsa CQ object with the resulting object selected
Return typeT
combineSolids(otherCQToCombine: Optional[Workplane] = None)→ Workplane[source]!!!DEPRECATED!!! use union() Combines all solids on the current stack, and any context object, together into a single object.
After the operation, the returned solid is also the context solid.
ParametersotherCQToCombine (Optional[Workplane]) – another CadQuery to combine.
Returnsa CQ object with the resulting combined solid on the stack.
Return typeWorkplane
Most of the time, both objects will contain a single solid, which is combined and returned on the stack of the new object.
compounds(selector: Optional[Union[str, Selector]] = None, tag: Optional[str] = None)→ T[source]Select compounds on the stack, optionally filtering the selection. If there are multiple objects on the stack, they are collected and a list of all the distinct compounds is returned.
Parameters- self (T) –

• selector (Optional[Union[str, Selector]]) – optional Selector object, or string selector expression (see StringSyntaxSelector)

• tag (Optional[str]) – if set, search the tagged object instead of self

Returnsa CQ object whose stack contains all of the distinct compounds of all objects on the current stack, filtered by the provided selector.
Return typeT
A compound contains multiple CAD primitives that resulted from a single operation, such as a union, cut, split, or fillet. Compounds can contain multiple edges, wires, or solids.
consolidateWires()→ T[source]Attempt to consolidate wires on the stack into a single. If possible, a new object with the results are returned. if not possible, the wires remain separated
Parametersself (T) –
Return typeT
copyWorkplane(obj: T)→ T[source]Copies the workplane from obj.
Parametersobj (a CQ object) – an object to copy the workplane from
Returnsa CQ object with obj’s workplane
Return typeT
cskHole(diameter: float, cskDiameter: float, cskAngle: float, depth: Optional[float] = None, clean: bool = True)→ T[source]Makes a countersunk hole for each item on the stack.
Parameters- self (T) –

• diameter (float > 0) – the diameter of the hole

• cskDiameter (float) – the diameter of the countersink, must be greater than hole diameter

• cskAngle (float > 0) – angle of the countersink, in degrees ( 82 is common )

• depth (float > 0 or None to drill thru the entire part.) – the depth of the hole

• clean (bool) – call clean() afterwards to have a clean shape

Return typeT
The surface of the hole is at the current workplane.
One hole is created for each item on the stack. A very common use case is to use a construction rectangle to define the centers of a set of holes, like so:

s = (
    Workplane()
    .box(2, 4, 0.5)
    .faces(">Z")
    .workplane()
    .rect(1.5, 3.5, forConstruction=True)
    .vertices()
    .cskHole(0.125, 0.25, 82, depth=None)
)

This sample creates a plate with a set of holes at the corners.
Plugin Note: this is one example of the power of plugins. CounterSunk holes are quite time consuming to create, but are quite easily defined by users.
see cboreHole() to make counterbores instead of countersinks
cut(toCut: Union[Workplane, Solid, Compound], clean: bool = True, tol: Optional[float] = None)→ T[source]Cuts the provided solid from the current solid, IE, perform a solid subtraction.
Parameters- self (T) –

• toCut (Union[Workplane, Solid, Compound]) – a solid object, or a Workplane object having a solid

• clean (bool) – call clean() afterwards to have a clean shape

• tol (Optional[float]) – tolerance value for fuzzy bool operation mode (default None)

RaisesValueError – if there is no solid to subtract from in the chain
Returnsa Workplane object with the resulting object selected
Return typeT
cutBlind(until: Union[float, Literal['next', 'last'], Face], clean: bool = True, both: bool = False, taper: Optional[float] = None)→ T[source]Use all un-extruded wires in the parent chain to create a prismatic cut from existing solid.
Specify either a distance value, or one of “next”, “last” to indicate a face to cut to.
Similar to extrude, except that a solid in the parent chain is required to remove material from. cutBlind always removes material from a part.
Parameters- self (T) –

• until (Union[float, Literal['next', 'last'], Face]) – The distance to cut to, normal to the workplane plane. When a negative float is passed the cut extends this far in the opposite direction to the normal of the plane (i.e in the solid). The string “next” cuts until the next face orthogonal to the wire normal. “last” cuts to the last face. If an object of type Face is passed, then the cut will extend until this face.

• clean (bool) – call clean() afterwards to have a clean shape

• both (bool) – cut in both directions symmetrically

• taper (Optional[float]) – angle for optional tapered extrusion

RaisesValueError – if there is no solid to subtract from in the chain
Returnsa CQ object with the resulting object selected
Return typeT
see cutThruAll() to cut material from the entire part
cutEach(fcn: Callable[[Location], Shape], useLocalCoords: bool = False, clean: bool = True)→ T[source]Evaluates the provided function at each point on the stack (ie, eachpoint) and then cuts the result from the context solid.
Parameters- self (T) –

• fcn (Callable[[Location], Shape]) – a function suitable for use in the eachpoint method: ie, that accepts a vector

• useLocalCoords (bool) – same as for eachpoint()

• clean (bool) – call clean() afterwards to have a clean shape

RaisesValueError – if no solids or compounds are found in the stack or parent chain
Returnsa CQ object that contains the resulting solid
Return typeT
cutThruAll(clean: bool = True, taper: float = 0)→ T[source]Use all un-extruded wires in the parent chain to create a prismatic cut from existing solid. Cuts through all material in both normal directions of workplane.
Similar to extrude, except that a solid in the parent chain is required to remove material from. cutThruAll always removes material from a part.
Parameters- self (T) –

• clean (bool) – call clean() afterwards to have a clean shape

• taper (float) –

Raises- ValueError – if there is no solid to subtract from in the chain

• ValueError – if there are no pending wires to cut with

Returnsa CQ object with the resulting object selected
Return typeT
see cutBlind() to cut material to a limited depth
cylinder(height: float, radius: float, direct: ~cadquery.occ_impl.geom.Vector = Vector: (0.0, 0.0, 1.0), angle: float = 360, centered: ~typing.Union[bool, ~typing.Tuple[bool, bool, bool]] = True, combine: ~typing.Union[bool, ~typing.Literal['cut', 'a', 's']] = True, clean: bool = True)→ T[source]Returns a cylinder with the specified radius and height for each point on the stack
Parameters- self (T) –

• height (float) – The height of the cylinder

• radius (float) – The radius of the cylinder

• direct (A three-tuple) – The direction axis for the creation of the cylinder

• angle (float > 0) – The angle to sweep the cylinder arc through

• centered (Union[bool, Tuple[bool, bool, bool]]) – If True, the cylinder will be centered around the reference point. If False, the corner of a bounding box around the cylinder will be on the reference point and it will extend in the positive x, y and z directions. Can also use a 3-tuple to specify centering along each axis.

• combine (true to combine shapes, false otherwise) – Whether the results should be combined with other solids on the stack (and each other)

• clean (bool) – call clean() afterwards to have a clean shape

ReturnsA cylinder object for each point on the stack
Return typeT
One cylinder is created for each item on the current stack. If no items are on the stack, one cylinder is created using the current workplane center.
If combine is true, the result will be a single object on the stack. If a solid was found in the chain, the result is that solid with all cylinders produced fused onto it otherwise, the result is the combination of all the produced cylinders.
If combine is false, the result will be a list of the cylinders produced.
each(callback: Callable[[Union[Vector, Location, Shape, Sketch]], Shape], useLocalCoordinates: bool = False, combine: Union[bool, Literal['cut', 'a', 's']] = True, clean: bool = True)→ T[source]Runs the provided function on each value in the stack, and collects the return values into a new CQ object.
Special note: a newly created workplane always has its center point as its only stack item
Parameters- self (T) –

• callBackFunction – the function to call for each item on the current stack.

• useLocalCoordinates (bool) – should values be converted from local coordinates first?

• combine (Union[bool, Literal['cut', 'a', 's']]) – True or “a” to combine the resulting solid with parent solids if found, “cut” or “s” to remove the resulting solid from the parent solids if found. False to keep the resulting solid separated from the parent solids.

• clean (bool) – call clean() afterwards to have a clean shape

• callback (Callable[[Union[Vector, Location, Shape, Sketch]], Shape]) –

Return typeT
The callback function must accept one argument, which is the item on the stack, and return one object, which is collected. If the function returns None, nothing is added to the stack. The object passed into the callBackFunction is potentially transformed to local coordinates, if useLocalCoordinates is true
useLocalCoordinates is very useful for plugin developers.
If false, the callback function is assumed to be working in global coordinates. Objects created are added as-is, and objects passed into the function are sent in using global coordinates
If true, the calling function is assumed to be working in local coordinates. Objects are transformed to local coordinates before they are passed into the callback method, and result objects are transformed to global coordinates after they are returned.
This allows plugin developers to create objects in local coordinates, without worrying about the fact that the working plane is different than the global coordinate system.
TODO: wrapper object for Wire will clean up forConstruction flag everywhere
eachpoint(callback: Callable[[Location], Shape], useLocalCoordinates: bool = False, combine: Union[bool, Literal['cut', 'a', 's']] = False, clean: bool = True)→ T[source]Same as each(), except each item on the stack is converted into a point before it is passed into the callback function.
ReturnsCadQuery object which contains a list of vectors (points ) on its stack.
Parameters- self (T) –

• useLocalCoordinates (bool) – should points be in local or global coordinates

• combine (Union[bool, Literal['cut', 'a', 's']]) – True or “a” to combine the resulting solid with parent solids if found, “cut” or “s” to remove the resulting solid from the parent solids if found. False to keep the resulting solid separated from the parent solids.

• clean (bool) – call clean() afterwards to have a clean shape

• callback (Callable[[Location], Shape]) –

Return typeT
The resulting object has a point on the stack for each object on the original stack. Vertices and points remain a point. Faces, Wires, Solids, Edges, and Shells are converted to a point by using their center of mass.
If the stack has zero length, a single point is returned, which is the center of the current workplane/coordinate system
edges(selector: Optional[Union[str, Selector]] = None, tag: Optional[str] = None)→ T[source]Select the edges of objects on the stack, optionally filtering the selection. If there are multiple objects on the stack, the edges of all objects are collected and a list of all the distinct edges is returned.
Parameters- self (T) –

• selector (Optional[Union[str, Selector]]) – optional Selector object, or string selector expression (see StringSyntaxSelector)

• tag (Optional[str]) – if set, search the tagged object instead of self

Returnsa CQ object whose stack contains all of the distinct edges of all objects on the current stack, filtered by the provided selector.
Return typeT
If there are no edges for any objects on the current stack, an empty CQ object is returned
The typical use is to select the edges of a single object on the stack. For example:

Workplane().box(1, 1, 1).faces("+Z").edges().size()

returns 4, because the topmost face of a cube will contain four edges. Similarly:

Workplane().box(1, 1, 1).edges().size()

returns 12, because a cube has a total of 12 edges, And:

Workplane().box(1, 1, 1).edges("|Z").size()

returns 4, because a cube has 4 edges parallel to the z direction
ellipse(x_radius: float, y_radius: float, rotation_angle: float = 0.0, forConstruction: bool = False)→ T[source]Make an ellipse for each item on the stack.
Parameters- self (T) –

• x_radius (float) – x radius of the ellipse (x-axis of plane the ellipse should lie in)

• y_radius (float) – y radius of the ellipse (y-axis of plane the ellipse should lie in)

• rotation_angle (float) – angle to rotate the ellipse

• forConstruction (true if the wires are for reference, false if they are creating part geometry) – should the new wires be reference geometry only?

Returnsa new CQ object with the created wires on the stack
Return typeT
NOTE Due to a bug in opencascade (tracker.dev.opencasc... ) the center of mass (equals center for next shape) is shifted. To create concentric ellipses use:

Workplane("XY").center(10, 20).ellipse(100, 10).center(0, 0).ellipse(50, 5)

ellipseArc(x_radius: float, y_radius: float, angle1: float = 360, angle2: float = 360, rotation_angle: float = 0.0, sense: Literal[- 1, 1] = 1, forConstruction: bool = False, startAtCurrent: bool = True, makeWire: bool = False)→ T[source]Draw an elliptical arc with x and y radiuses either with start point at current point or or current point being the center of the arc
Parameters- self (T) –

• x_radius (float) – x radius of the ellipse (along the x-axis of plane the ellipse should lie in)

• y_radius (float) – y radius of the ellipse (along the y-axis of plane the ellipse should lie in)

• angle1 (float) – start angle of arc

• angle2 (float) – end angle of arc (angle2 == angle1 return closed ellipse = default)

• rotation_angle (float) – angle to rotate the created ellipse / arc

• sense (Literal[-1, 1]) – clockwise (-1) or counter clockwise (1)

• startAtCurrent (bool) – True: start point of arc is moved to current point; False: center of arc is on current point

• makeWire (bool) – convert the resulting arc edge to a wire

• forConstruction (bool) –

Return typeT
end(n: int = 1)→ Workplane[source]Return the nth parent of this CQ element
Parametersn (int) – number of ancestor to return (default: 1)
Return typea CQ object
RaisesValueError if there are no more parents in the chain.
For example:

CQ(obj).faces("+Z").vertices().end()

will return the same as:

CQ(obj).faces("+Z")

exportSvg(fileName: str)→ None[source]Exports the first item on the stack as an SVG file
For testing purposes mainly.
ParametersfileName (str) – the filename to export, absolute path to the file
Return typeNone
extrude(until: Union[float, Literal['next', 'last'], Face], combine: Union[bool, Literal['cut', 'a', 's']] = True, clean: bool = True, both: bool = False, taper: Optional[float] = None)→ T[source]Use all un-extruded wires in the parent chain to create a prismatic solid.
Parameters- self (T) –

• until (Union[float, Literal['next', 'last'], Face]) – The distance to extrude, normal to the workplane plane. When a float is passed, the extrusion extends this far and a negative value is in the opposite direction to the normal of the plane. The string “next” extrudes until the next face orthogonal to the wire normal. “last” extrudes to the last face. If a object of type Face is passed then the extrusion will extend until this face. Note that the Workplane must contain a Solid for extruding to a given face.

• combine (Union[bool, Literal['cut', 'a', 's']]) – True or “a” to combine the resulting solid with parent solids if found, “cut” or “s” to remove the resulting solid from the parent solids if found. False to keep the resulting solid separated from the parent solids.

• clean (bool) – call clean() afterwards to have a clean shape

• both (bool) – extrude in both directions symmetrically

• taper (Optional[float]) – angle for optional tapered extrusion

Returnsa CQ object with the resulting solid selected.
Return typeT
The returned object is always a CQ object, and depends on whether combine is True, and whether a context solid is already defined:

• if combine is False, the new value is pushed onto the stack. Note that when extrudinguntil a specified face, combine can not be False

• if combine is true, the value is combined with the context solid if it exists,and the resulting solid becomes the new context solid.

faces(selector: Optional[Union[str, Selector]] = None, tag: Optional[str] = None)→ T[source]Select the faces of objects on the stack, optionally filtering the selection. If there are multiple objects on the stack, the faces of all objects are collected and a list of all the distinct faces is returned.
Parameters- self (T) –

• selector (Optional[Union[str, Selector]]) – optional Selector object, or string selector expression (see StringSyntaxSelector)

• tag (Optional[str]) – if set, search the tagged object instead of self

Returnsa CQ object whose stack contains all of the distinct faces of all objects on the current stack, filtered by the provided selector.
Return typeT
If there are no faces for any objects on the current stack, an empty CQ object is returned.
The typical use is to select the faces of a single object on the stack. For example:

Workplane().box(1, 1, 1).faces("+Z").size()

returns 1, because a cube has one face with a normal in the +Z direction. Similarly:

Workplane().box(1, 1, 1).faces().size()

returns 6, because a cube has a total of 6 faces, And:

Workplane().box(1, 1, 1).faces("|Z").size()

returns 2, because a cube has 2 faces having normals parallel to the z direction
fillet(radius: float)→ T[source]Fillets a solid on the selected edges.
The edges on the stack are filleted. The solid to which the edges belong must be in the parent chain of the selected edges.
Parameters- self (T) –

• radius (float) – the radius of the fillet, must be > zero

Raises- ValueError – if at least one edge is not selected

• ValueError – if the solid containing the edge is not in the chain

ReturnsCQ object with the resulting solid selected.
Return typeT
This example will create a unit cube, with the top edges filleted:

s = Workplane().box(1, 1, 1).faces("+Z").edges().fillet(0.1)

findFace(searchStack: bool = True, searchParents: bool = True)→ Face[source]Finds the first face object in the chain, searching from the current node backwards through parents until one is found.
Parameters- searchStack (bool) – should objects on the stack be searched first.

• searchParents (bool) – should parents be searched?

ReturnsA face or None if no face is found.
Return typeFace
findSolid(searchStack: bool = True, searchParents: bool = True)→ Union[Solid, Compound][source]Finds the first solid object in the chain, searching from the current node backwards through parents until one is found.
Parameters- searchStack (bool) – should objects on the stack be searched first?

• searchParents (bool) – should parents be searched?

RaisesValueError – if no solid is found
Return typeUnion[Solid, Compound]
This function is very important for chains that are modifying a single parent object, most often a solid.
Most of the time, a chain defines or selects a solid, and then modifies it using workplanes or other operations.
Plugin Developers should make use of this method to find the solid that should be modified, if the plugin implements a unary operation, or if the operation will automatically merge its results with an object already on the stack.
first()→ T[source]Return the first item on the stack
Returnsthe first item on the stack.
Return typea CQ object
Parametersself (T) –
hLine(distance: float, forConstruction: bool = False)→ T[source]Make a horizontal line from the current point the provided distance
Parameters- self (T) –

• distance (float) –

  1. distance from current point

• forConstruction (bool) –

Returnsthe Workplane object with the current point at the end of the new line
Return typeT
hLineTo(xCoord: float, forConstruction: bool = False)→ T[source]Make a horizontal line from the current point to the provided x coordinate.
Useful if it is more convenient to specify the end location rather than distance, as in hLine()
Parameters- self (T) –

• xCoord (float) – x coordinate for the end of the line

• forConstruction (bool) –

Returnsthe Workplane object with the current point at the end of the new line
Return typeT
hole(diameter: float, depth: Optional[float] = None, clean: bool = True)→ T[source]Makes a hole for each item on the stack.
Parameters- self (T) –

• diameter (float) – the diameter of the hole

• depth (float > 0 or None to drill thru the entire part.) – the depth of the hole

• clean (bool) – call clean() afterwards to have a clean shape

Return typeT
The surface of the hole is at the current workplane.
One hole is created for each item on the stack. A very common use case is to use a construction rectangle to define the centers of a set of holes, like so:

s = (
    Workplane()
    .box(2, 4, 0.5)
    .faces(">Z")
    .workplane()
    .rect(1.5, 3.5, forConstruction=True)
    .vertices()
    .hole(0.125, 0.25, 82, depth=None)
)

This sample creates a plate with a set of holes at the corners.
Plugin Note: this is one example of the power of plugins. CounterSunk holes are quite time consuming to create, but are quite easily defined by users.
see cboreHole() and cskHole() to make counterbores or countersinks
interpPlate(surf_edges: Union[Sequence[Union[Tuple[float, float], Tuple[float, float, float], Vector]], Sequence[Union[Edge, Wire]], Workplane], surf_pts: Sequence[Union[Tuple[float, float], Tuple[float, float, float], Vector]] = [], thickness: float = 0, combine: Union[bool, Literal['cut', 'a', 's']] = False, clean: bool = True, degree: int = 3, nbPtsOnCur: int = 15, nbIter: int = 2, anisotropy: bool = False, tol2d: float = 1e-05, tol3d: float = 0.0001, tolAng: float = 0.01, tolCurv: float = 0.1, maxDeg: int = 8, maxSegments: int = 9)→ T[source]Returns a plate surface that is ‘thickness’ thick, enclosed by ‘surf_edge_pts’ points, and going through ‘surf_pts’ points. Using pushPoints directly with interpPlate and combine=True, can be very resource intensive depending on the complexity of the shape. In this case set combine=False.
Parameters- self (T) –

• surf_edges (Union[Sequence[Union[Tuple[float, float], Tuple[float, float, float], Vector]], Sequence[Union[Edge, Wire]], Workplane]) – list of [x,y,z] ordered coordinates or list of ordered or unordered edges, wires

• surf_pts (Sequence[Union[Tuple[float, float], Tuple[float, float, float], Vector]]) – list of points (uses only edges if [])

• thickness (float) – value may be negative or positive depending on thickening direction (2D surface if 0)

• combine (Union[bool, Literal['cut', 'a', 's']]) – should the results be combined with other solids on the stack (and each other)?

• clean (bool) – call clean() afterwards to have a clean shape

• degree (int) – >= 2

• nbPtsOnCur (int) – number of points on curve >= 15

• nbIter (int) – number of iterations >= 2

• anisotropy (bool) – = bool Anisotropy

• tol2d (float) – 2D tolerance

• tol3d (float) – 3D tolerance

• tolAng (float) – angular tolerance

• tolCurv (float) – tolerance for curvature

• maxDeg (int) – highest polynomial degree >= 2

• maxSegments (int) – greatest number of segments >= 2

Return typeT
intersect(toIntersect: Union[Workplane, Solid, Compound], clean: bool = True, tol: Optional[float] = None)→ T[source]Intersects the provided solid from the current solid.
Parameters- self (T) –

• toIntersect (Union[Workplane, Solid, Compound]) – a solid object, or a Workplane object having a solid

• clean (bool) – call clean() afterwards to have a clean shape

• tol (Optional[float]) – tolerance value for fuzzy bool operation mode (default None)

RaisesValueError – if there is no solid to intersect with in the chain
Returnsa Workplane object with the resulting object selected
Return typeT
item(i: int)→ T[source]Return the ith item on the stack.
Return typea CQ object
Parameters- self (T) –

• i (int) –

largestDimension()→ float[source]Finds the largest dimension in the stack.
Used internally to create thru features, this is how you can compute how long or wide a feature must be to make sure to cut through all of the material
RaisesValueError – if no solids or compounds are found
ReturnsA value representing the largest dimension of the first solid on the stack
Return typefloat
last()→ T[source]Return the last item on the stack.
Return typea CQ object
Parametersself (T) –
line(xDist: float, yDist: float, forConstruction: bool = False)→ T[source]Make a line from the current point to the provided point, using dimensions relative to the current point
Parameters- self (T) –

• xDist (float) – x distance from current point

• yDist (float) – y distance from current point

• forConstruction (bool) –

Returnsthe workplane object with the current point at the end of the new line
Return typeT
see lineTo() if you want to use absolute coordinates to make a line instead.
lineTo(x: float, y: float, forConstruction: bool = False)→ T[source]Make a line from the current point to the provided point
Parameters- self (T) –

• x (float) – the x point, in workplane plane coordinates

• y (float) – the y point, in workplane plane coordinates

• forConstruction (bool) –

Returnsthe Workplane object with the current point at the end of the new line
Return typeT
See line() if you want to use relative dimensions to make a line instead.
loft(ruled: bool = False, combine: Union[bool, Literal['cut', 'a', 's']] = True, clean: bool = True)→ T[source]Make a lofted solid, through the set of wires.
Parameters- self (T) –

• ruled (bool) – When set to True connects each section linearly and without continuity

• combine (Union[bool, Literal['cut', 'a', 's']]) – True or “a” to combine the resulting solid with parent solids if found, “cut” or “s” to remove the resulting solid from the parent solids if found. False to keep the resulting solid separated from the parent solids.

• clean (bool) – call clean() afterwards to have a clean shape

Returnsa Workplane object containing the created loft
Return typeT
mirror(mirrorPlane: Union[Literal['XY', 'YX', 'XZ', 'ZX', 'YZ', 'ZY'], Tuple[float, float], Tuple[float, float, float], Vector, Face, Workplane] = 'XY', basePointVector: Optional[Union[Tuple[float, float], Tuple[float, float, float], Vector]] = None, union: bool = False)→ T[source]Mirror a single CQ object.
Parameters- self (T) –

• mirrorPlane (string, one of "XY", "YX", "XZ", "ZX", "YZ", "ZY" the planes or the normal vector of the plane eg (1,0,0) or a Face object) – the plane to mirror about

• basePointVector (Optional[Union[Tuple[float, float], Tuple[float, float, float], Vector]]) – the base point to mirror about (this is overwritten if a Face is passed)

• union (bool) – If true will perform a union operation on the mirrored object

Return typeT
mirrorX()→ T[source]Mirror entities around the x axis of the workplane plane.
Returnsa new object with any free edges consolidated into as few wires as possible.
Parametersself (T) –
Return typeT
All free edges are collected into a wire, and then the wire is mirrored, and finally joined into a new wire
Typically used to make creating wires with symmetry easier.
mirrorY()→ T[source]Mirror entities around the y axis of the workplane plane.
Returnsa new object with any free edges consolidated into as few wires as possible.
Parametersself (T) –
Return typeT
All free edges are collected into a wire, and then the wire is mirrored, and finally joined into a new wire
Typically used to make creating wires with symmetry easier. This line of code:

s = Workplane().lineTo(2, 2).threePointArc((3, 1), (2, 0)).mirrorX().extrude(0.25)

Produces a flat, heart shaped object
move(xDist: float = 0, yDist: float = 0)→ T[source]Move the specified distance from the current point, without drawing.
Parameters- self (T) –

• xDist (float, or none for zero) – desired x distance, in local coordinates

• yDist (float, or none for zero.) – desired y distance, in local coordinates

Return typeT
Not to be confused with center(), which moves the center of the entire workplane, this method only moves the current point ( and therefore does not affect objects already drawn ).
See moveTo() to do the same thing but using absolute coordinates
moveTo(x: float = 0, y: float = 0)→ T[source]Move to the specified point, without drawing.
Parameters- self (T) –

• x (float, or none for zero) – desired x location, in local coordinates

• y (float, or none for zero.) – desired y location, in local coordinates

Return typeT
Not to be confused with center(), which moves the center of the entire workplane, this method only moves the current point ( and therefore does not affect objects already drawn ).
See move() to do the same thing but using relative dimensions
newObject(objlist: Iterable[Union[Vector, Location, Shape, Sketch]])→ T[source]Create a new workplane object from this one.
Overrides CQ.newObject, and should be used by extensions, plugins, and subclasses to create new objects.
Parameters- self (T) –

• objlist (a list of CAD primitives) – new objects to put on the stack

Returnsa new Workplane object with the current workplane as a parent.
Return typeT
offset2D(d: float, kind: Literal['arc', 'intersection', 'tangent'] = 'arc', forConstruction: bool = False)→ T[source]Creates a 2D offset wire.
Parameters- self (T) –

• d (float) – thickness. Negative thickness denotes offset to inside.

• kind (Literal['arc', 'intersection', 'tangent']) – offset kind. Use “arc” for rounded and “intersection” for sharp edges (default: “arc”)

• forConstruction (bool) – Should the result be added to pending wires?

ReturnsCQ object with resulting wire(s).
Return typeT
parametricCurve(func: Callable[[float], Union[Tuple[float, float], Tuple[float, float, float], Vector]], N: int = 400, start: float = 0, stop: float = 1, tol: float = 1e-06, minDeg: int = 1, maxDeg: int = 6, smoothing: Optional[Tuple[float, float, float]] = (1, 1, 1), makeWire: bool = True)→ T[source]Create a spline curve approximating the provided function.
Parameters- self (T) –

• func (float --> (float,float,float)) – function f(t) that will generate (x,y,z) pairs

• N (int) – number of points for discretization

• start (float) – starting value of the parameter t

• stop (float) – final value of the parameter t

• tol (float) – tolerance of the algorithm (default: 1e-6)

• minDeg (int) – minimum spline degree (default: 1)

• maxDeg (int) – maximum spline degree (default: 6)

• smoothing (Optional[Tuple[float, float, float]]) – optional parameters for the variational smoothing algorithm (default: (1,1,1))

• makeWire (bool) – convert the resulting spline edge to a wire

Returnsa Workplane object with the current point unchanged
Return typeT
parametricSurface(func: Callable[[float, float], Union[Tuple[float, float], Tuple[float, float, float], Vector]], N: int = 20, start: float = 0, stop: float = 1, tol: float = 0.01, minDeg: int = 1, maxDeg: int = 6, smoothing: Optional[Tuple[float, float, float]] = (1, 1, 1))→ T[source]Create a spline surface approximating the provided function.
Parameters- self (T) –

• func ((float,float) --> (float,float,float)) – function f(u,v) that will generate (x,y,z) pairs

• N (int) – number of points for discretization in one direction

• start (float) – starting value of the parameters u,v

• stop (float) – final value of the parameters u,v

• tol (float) – tolerance used by the approximation algorithm (default: 1e-3)

• minDeg (int) – minimum spline degree (default: 1)

• maxDeg (int) – maximum spline degree (default: 3)

• smoothing (Optional[Tuple[float, float, float]]) – optional parameters for the variational smoothing algorithm (default: (1,1,1))

Returnsa Workplane object with the current point unchanged
Return typeT
This method might be unstable and may require tuning of the tol parameter.
placeSketch(sketches: Sketch)→ T[source]Place the provided sketch(es) based on the current items on the stack.
ReturnsWorkplane object with the sketch added.
Parameters- *self** (T) –

• sketches (Sketch) –

Return typeT
polarArray(radius: float, startAngle: float, angle: float, count: int, fill: bool = True, rotate: bool = True)→ T[source]Creates a polar array of points and pushes them onto the stack. The zero degree reference angle is located along the local X-axis.
Parameters- self (T) –

• radius (float) – Radius of the array.

• startAngle (float) – Starting angle (degrees) of array. Zero degrees is situated along the local X-axis.

• angle (float) – The angle (degrees) to fill with elements. A positive value will fill in the counter-clockwise direction. If fill is False, angle is the angle between elements.

• count (int) – Number of elements in array. (count >= 1)

• fill (bool) – Interpret the angle as total if True (default: True).

• rotate (bool) – Rotate every item (default: True).

Return typeT
polarLine(distance: float, angle: float, forConstruction: bool = False)→ T[source]Make a line of the given length, at the given angle from the current point
Parameters- self (T) –

• distance (float) – distance of the end of the line from the current point

• angle (float) – angle of the vector to the end of the line with the x-axis

• forConstruction (bool) –

Returnsthe Workplane object with the current point at the end of the new line
Return typeT
polarLineTo(distance: float, angle: float, forConstruction: bool = False)→ T[source]Make a line from the current point to the given polar coordinates
Useful if it is more convenient to specify the end location rather than the distance and angle from the current point
Parameters- self (T) –

• distance (float) – distance of the end of the line from the origin

• angle (float) – angle of the vector to the end of the line with the x-axis

• forConstruction (bool) –

Returnsthe Workplane object with the current point at the end of the new line
Return typeT
polygon(nSides: int, diameter: float, forConstruction: bool = False, circumscribed: bool = False)→ T[source]Make a polygon for each item on the stack.
By default, each polygon is created by inscribing it in a circle of the specified diameter, such that the first vertex is oriented in the x direction. Alternatively, each polygon can be created by circumscribing it around a circle of the specified diameter, such that the midpoint of the first edge is oriented in the x direction. Circumscribed polygons are thus rotated by pi/nSides radians relative to the inscribed polygon. This ensures the extent of the polygon along the positive x-axis is always known. This has the advantage of not requiring additional formulae for purposes such as tiling on the x-axis (at least for even sided polygons).
Parameters- self (T) –

• nSides (int) – number of sides, must be >= 3

• diameter (float) – the diameter of the circle for constructing the polygon

• circumscribed (true to create the polygon by circumscribing it about a circle, false to create the polygon by inscribing it in a circle) – circumscribe the polygon about a circle

• forConstruction (bool) –

Returnsa polygon wire
Return typeT
polyline(listOfXYTuple: Sequence[Union[Tuple[float, float], Tuple[float, float, float], Vector]], forConstruction: bool = False, includeCurrent: bool = False)→ T[source]Create a polyline from a list of points
Parameters- self (T) –

• listOfXYTuple (Sequence[Union[Tuple[float, float], Tuple[float, float, float], Vector]]) – a list of points in Workplane coordinates (2D or 3D)

• forConstruction (true if the edges are for reference, false if they are for creating geometry part geometry) – whether or not the edges are used for reference

• includeCurrent (bool) – use current point as a starting point of the polyline

Returnsa new CQ object with a list of edges on the stack
Return typeT
NOTE most commonly, the resulting wire should be closed.
pushPoints(pntList: Iterable[Union[Tuple[float, float], Tuple[float, float, float], Vector, Location]])→ T[source]Pushes a list of points onto the stack as vertices. The points are in the 2D coordinate space of the workplane face
Parameters- self (T) –

• pntList (list of 2-tuples, in local coordinates) – a list of points to push onto the stack

Returnsa new workplane with the desired points on the stack.
Return typeT
A common use is to provide a list of points for a subsequent operation, such as creating circles or holes. This example creates a cube, and then drills three holes through it, based on three points:

s = (
    Workplane()
    .box(1, 1, 1)
    .faces(">Z")
    .workplane()
    .pushPoints([(-0.3, 0.3), (0.3, 0.3), (0, 0)])
)
body = s.circle(0.05).cutThruAll()

Here the circle function operates on all three points, and is then extruded to create three holes. See circle() for how it works.
radiusArc(endPoint: Union[Tuple[float, float], Tuple[float, float, float], Vector], radius: float, forConstruction: bool = False)→ T[source]Draw an arc from the current point to endPoint with an arc defined by the radius.
Parameters- self (T) –

• endPoint (2-tuple, in workplane coordinates) – end point for the arc

• radius (float, the radius of the arc between start point and end point.) – the radius of the arc

• forConstruction (bool) –

Returnsa workplane with the current point at the end of the arc
Return typeT
Given that a closed contour is drawn clockwise; A positive radius means convex arc and negative radius means concave arc.
rarray(xSpacing: float, ySpacing: float, xCount: int, yCount: int, center: Union[bool, Tuple[bool, bool]] = True)→ T[source]Creates an array of points and pushes them onto the stack. If you want to position the array at another point, create another workplane that is shifted to the position you would like to use as a reference
Parameters- self (T) –

• xSpacing (float) – spacing between points in the x direction ( must be > 0)

• ySpacing (float) – spacing between points in the y direction ( must be > 0)

• xCount (int) – number of points ( > 0 )

• yCount (int) – number of points ( > 0 )

• center (Union[bool, Tuple[bool, bool]]) – If True, the array will be centered around the workplane center. If False, the lower corner will be on the reference point and the array will extend in the positive x and y directions. Can also use a 2-tuple to specify centering along each axis.

Return typeT
rect(xLen: float, yLen: float, centered: Union[bool, Tuple[bool, bool]] = True, forConstruction: bool = False)→ T[source]Make a rectangle for each item on the stack.
Parameters- self (T) –

• xLen (float) – length in the x direction (in workplane coordinates)

• yLen (float) – length in the y direction (in workplane coordinates)

• centered (Union[bool, Tuple[bool, bool]]) – If True, the rectangle will be centered around the reference point. If False, the corner of the rectangle will be on the reference point and it will extend in the positive x and y directions. Can also use a 2-tuple to specify centering along each axis.

• forConstruction (true if the wires are for reference, false if they are creating part geometry) – should the new wires be reference geometry only?

Returnsa new CQ object with the created wires on the stack
Return typeT
A common use case is to use a for-construction rectangle to define the centers of a hole pattern:

s = Workplane().rect(4.0, 4.0, forConstruction=True).vertices().circle(0.25)

Creates 4 circles at the corners of a square centered on the origin.
Negative values for xLen and yLen are permitted, although they only have an effect when centered is False.
Future Enhancements:- project points not in the workplane plane onto the workplane plane

revolve(angleDegrees: float = 360.0, axisStart: Optional[Union[Tuple[float, float], Tuple[float, float, float], Vector]] = None, axisEnd: Optional[Union[Tuple[float, float], Tuple[float, float, float], Vector]] = None, combine: Union[bool, Literal['cut', 'a', 's']] = True, clean: bool = True)→ T[source]Use all un-revolved wires in the parent chain to create a solid.
Parameters- self (T) –

• angleDegrees (float, anything less than 360 degrees will leave the shape open) – the angle to revolve through.

• axisStart (Optional[Union[Tuple[float, float], Tuple[float, float, float], Vector]]) – the start point of the axis of rotation

• axisEnd (Optional[Union[Tuple[float, float], Tuple[float, float, float], Vector]]) – the end point of the axis of rotation

• combine (Union[bool, Literal['cut', 'a', 's']]) – True or “a” to combine the resulting solid with parent solids if found, “cut” or “s” to remove the resulting solid from the parent solids if found. False to keep the resulting solid separated from the parent solids.

• clean (bool) – call clean() afterwards to have a clean shape

Returnsa CQ object with the resulting solid selected.
Return typeT
The returned object is always a CQ object, and depends on whether combine is True, and whether a context solid is already defined:

• if combine is False, the new value is pushed onto the stack.

• if combine is true, the value is combined with the context solid if it exists, and the resulting solid becomes the new context solid.

Note
Keep in mind that axisStart and axisEnd are defined relative to the current Workplane center position. So if for example you want to revolve a circle centered at (10,0,0) around the Y axis, be sure to either move() (or moveTo()) the current Workplane position or specify axisStart and axisEnd with the correct vector position. In this example (0,0,0), (0,1,0) as axis coords would fail.
rotate(axisStartPoint: Union[Tuple[float, float], Tuple[float, float, float], Vector], axisEndPoint: Union[Tuple[float, float], Tuple[float, float, float], Vector], angleDegrees: float)→ T[source]Returns a copy of all of the items on the stack rotated through and angle around the axis of rotation.
Parameters- self (T) –

• axisStartPoint (a 3-tuple of floats) – The first point of the axis of rotation

• axisEndPoint (a 3-tuple of floats) – The second point of the axis of rotation

• angleDegrees (float) – the rotation angle, in degrees

Returnsa CQ object
Return typeT
rotateAboutCenter(axisEndPoint: Union[Tuple[float, float], Tuple[float, float, float], Vector], angleDegrees: float)→ T[source]Rotates all items on the stack by the specified angle, about the specified axis
The center of rotation is a vector starting at the center of the object on the stack, and ended at the specified point.
Parameters- self (T) –

• axisEndPoint (a three-tuple in global coordinates) – the second point of axis of rotation

• angleDegrees (float) – the rotation angle, in degrees

Returnsa CQ object, with all items rotated.
Return typeT
WARNING: This version returns the same CQ object instead of a new one– the old object is not accessible.
Future Enhancements:- A version of this method that returns a transformed copy, rather than modifying the originals

• This method doesn’t expose a very good interface, because the axis of rotation could be inconsistent between multiple objects. This is because the beginning of the axis is variable, while the end is fixed. This is fine when operating on one object, but is not cool for multiple.

sagittaArc(endPoint: Union[Tuple[float, float], Tuple[float, float, float], Vector], sag: float, forConstruction: bool = False)→ T[source]Draw an arc from the current point to endPoint with an arc defined by the sag (sagitta).
Parameters- self (T) –

• endPoint (2-tuple, in workplane coordinates) – end point for the arc

• sag (float, perpendicular distance from arc center to arc baseline.) – the sagitta of the arc

• forConstruction (bool) –

Returnsa workplane with the current point at the end of the arc
Return typeT
The sagitta is the distance from the center of the arc to the arc base. Given that a closed contour is drawn clockwise; A positive sagitta means convex arc and negative sagitta means concave arc. See en.wikipedia.org/wik...(geometry) for more information.
section(height: float = 0.0)→ T[source]Slices current solid at the given height.
Parameters- self (T) –

• height (float) – height to slice at (default: 0)

RaisesValueError – if no solids or compounds are found
Returnsa CQ object with the resulting face(s).
Return typeT
shell(thickness: float, kind: Literal['arc', 'intersection'] = 'arc')→ T[source]Remove the selected faces to create a shell of the specified thickness.
To shell, first create a solid, and in the same chain select the faces you wish to remove.
Parameters- self (T) –

• thickness (float) – thickness of the desired shell. Negative values shell inwards, positive values shell outwards.

• kind (Literal['arc', 'intersection']) – kind of join, arc or intersection (default: arc).

RaisesValueError – if the current stack contains objects that are not faces of a solid further up in the chain.
Returnsa CQ object with the resulting shelled solid selected.
Return typeT
This example will create a hollowed out unit cube, where the top most face is open, and all other walls are 0.2 units thick:

Workplane().box(1, 1, 1).faces("+Z").shell(0.2)

You can also select multiple faces at once. Here is an example that creates a three-walled corner, by removing three faces of a cube:

Workplane().box(10, 10, 10).faces(">Z or >X or <Y").shell(1)

Note: When sharp edges are shelled inwards, they remain sharp corners, but outward shells are automatically filleted (unless kind=”intersection”), because an outward offset from a corner generates a radius.
shells(selector: Optional[Union[str, Selector]] = None, tag: Optional[str] = None)→ T[source]Select the shells of objects on the stack, optionally filtering the selection. If there are multiple objects on the stack, the shells of all objects are collected and a list of all the distinct shells is returned.
Parameters- self (T) –

• selector (Optional[Union[str, Selector]]) – optional Selector object, or string selector expression (see StringSyntaxSelector)

• tag (Optional[str]) – if set, search the tagged object instead of self

Returnsa CQ object whose stack contains all of the distinct shells of all objects on the current stack, filtered by the provided selector.
Return typeT
If there are no shells for any objects on the current stack, an empty CQ object is returned
Most solids will have a single shell, which represents the outer surface. A shell will typically be composed of multiple faces.
siblings(kind: Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound'], level: int = 1, tag: Optional[str] = None)→ T[source]Select topological siblings.
Parameters- self (T) –

• kind (Literal['Vertex', 'Edge', 'Wire', 'Face', 'Shell', 'Solid', 'CompSolid', 'Compound']) – kind of linking element, e.g. “Vertex” or “Edge”

• level (int) – level of relation - how many elements of kind are in the link

• tag (Optional[str]) – if set, search the tagged object instead of self

Returnsa Workplane object whose stack contains selected siblings.
Return typeT
size()→ int[source]Return the number of objects currently on the stack
Return typeint
sketch()→ Sketch[source]Initialize and return a sketch
ReturnsSketch object with the current workplane as a parent.
Parametersself (T) –
Return typeSketch
slot2D(length: float, diameter: float, angle: float = 0)→ T[source]Creates a rounded slot for each point on the stack.
Parameters- self (T) –

• diameter (float) – desired diameter, or width, of slot

• length (float) – desired end to end length of slot

• angle (float) – angle of slot in degrees, with 0 being along x-axis

Returnsa new CQ object with the created wires on the stack
Return typeT
Can be used to create arrays of slots, such as in cooling applications:

Workplane().box(10, 25, 1).rarray(1, 2, 1, 10).slot2D(8, 1, 0).cutThruAll()